[minion] Propose features from monitored sources

.github/workflows/doc-minion.yml

@@ -19,23 +19,20 @@ permissions:
 
 jobs:
   update-docs:
-    runs-on: ubuntu-latest
+    runs-on: github-runner-partio-minion-ai-01
     timeout-minutes: 15
 
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install Claude Code
-        run: npm install -g @anthropic-ai/claude-code
 
       - name: Install minions
         run: |
-          go install github.com/partio-io/minions/cmd/minions@v0.0.3
+          go install github.com/partio-io/minions/cmd/minions@v0.0.5
           echo "$(go env GOPATH)/bin" >> "$GITHUB_PATH"
 
       - name: Run doc-update program
         env:
-          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
           GH_TOKEN: ${{ secrets.GH_PAT }}
         run: |
           ARGS="run .minions/programs/doc-update.md"

.github/workflows/minion.yml

@@ -30,7 +30,7 @@ jobs:
       github.event_name == 'workflow_dispatch' ||
       (github.event_name == 'issues' && (github.event.label.name == 'minion-ready' || github.event.label.name == 'minion-approved')) ||
       (github.event_name == 'issue_comment' && contains(github.event.comment.body, '/minion build'))
-    runs-on: ubuntu-latest
+    runs-on: github-runner-partio-minion-ai-01
     timeout-minutes: 30
 
     steps:
@@ -52,17 +52,14 @@ jobs:
             echo "issue_num=${ISSUE_NUM}" >> "$GITHUB_OUTPUT"
           fi
 
-      - name: Install Claude Code
-        run: npm install -g @anthropic-ai/claude-code
 
       - name: Install minions
         run: |
-          go install github.com/partio-io/minions/cmd/minions@v0.0.3
+          go install github.com/partio-io/minions/cmd/minions@v0.0.5
           echo "$(go env GOPATH)/bin" >> "$GITHUB_PATH"
 
       - name: Run program
         env:
-          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
           GH_TOKEN: ${{ secrets.GH_PAT }}
         run: |
           ARGS="run ${{ steps.program.outputs.path }}"

.github/workflows/plan.yml

@@ -19,18 +19,16 @@ jobs:
     if: >
       github.event_name == 'workflow_dispatch' ||
       (github.event_name == 'issues' && github.event.label.name == 'minion-planning')
-    runs-on: ubuntu-latest
+    runs-on: github-runner-partio-minion-ai-01
     timeout-minutes: 15
 
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install Claude Code
-        run: npm install -g @anthropic-ai/claude-code
 
       - name: Install minions
         run: |
-          go install github.com/partio-io/minions/cmd/minions@v0.0.3
+          go install github.com/partio-io/minions/cmd/minions@v0.0.5
           echo "$(go env GOPATH)/bin" >> "$GITHUB_PATH"
 
       - name: Determine program
@@ -53,6 +51,5 @@ jobs:
 
       - name: Run program with planner
         env:
-          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
           GH_TOKEN: ${{ secrets.GH_PAT }}
         run: minions run ${{ steps.program.outputs.path }} --dry-run

.github/workflows/propose.yml

@@ -17,23 +17,20 @@ permissions:
 
 jobs:
   propose:
-    runs-on: ubuntu-latest
+    runs-on: github-runner-partio-minion-ai-01
     timeout-minutes: 15
 
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install Claude Code
-        run: npm install -g @anthropic-ai/claude-code
 
       - name: Install minions
         run: |
-          go install github.com/partio-io/minions/cmd/minions@v0.0.3
+          go install github.com/partio-io/minions/cmd/minions@v0.0.5
           echo "$(go env GOPATH)/bin" >> "$GITHUB_PATH"
 
       - name: Run propose program
         env:
-          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
           GH_TOKEN: ${{ secrets.GH_PAT }}
         run: |
           ARGS="run .minions/programs/propose.md"

.minions/programs/actionable-hook-error-messages.md

@@ -0,0 +1,33 @@
+---
+id: actionable-hook-error-messages
+target_repos:
+  - cli
+acceptance_criteria:
+  - Common hook failure modes are classified into distinct error types with user-facing messages
+  - Each error type includes a short description and a suggested remediation action
+  - Hook error output includes the error classification when running with default log level
+  - At least these failure modes are classified: session not found, JSONL parse failure, git plumbing error, permission denied, checkpoint branch missing
+  - Unit tests verify that each classified error produces the expected message and suggestion
+pr_labels:
+  - minion
+---
+
+# Classify common hook and checkpoint errors into actionable user messages
+
+## Summary
+
+Replace generic error logging in Partio's hook implementations with classified, actionable error messages that tell users what went wrong and how to fix it.
+
+## Motivation
+
+When Partio hooks fail during git operations, users currently see raw error strings from Go's error wrapping (e.g., "failed to create checkpoint: exit status 128") with no guidance on what to do. Similar tools (entireio/cli#963) found that classifying CLI errors into categories with remediation suggestions dramatically reduces support burden and user frustration.
+
+Partio's hooks run silently by design (to avoid blocking git), but when something does go wrong, the logged warning should be immediately actionable — not require users to search documentation or open issues.
+
+## Implementation hints
+
+- Define an error classification type in `internal/hooks/` or a shared errors package with fields: `Code`, `Message`, `Suggestion`
+- Classify at least: `SessionNotFound` ("No active agent session detected" / "Run `partio status` to check agent detection"), `JSONLParseError` ("Failed to parse session transcript" / "Check if the agent session file is corrupted"), `GitPlumbingError` ("Git object write failed" / "Run `partio doctor` to check repository health"), `PermissionDenied` ("Cannot write to git object database" / "Check file permissions on .git/objects/"), `CheckpointBranchMissing` ("Checkpoint branch not found" / "Run `partio enable` to reinitialize")
+- Wrap existing error returns in hook implementations with the classifier
+- Surface the classification in log output at warn level (visible by default)
+- Keep the raw error available at debug level for advanced troubleshooting

.minions/programs/add-sessions-subcommands.md

@@ -0,0 +1,45 @@
+---
+id: add-sessions-subcommands
+target_repos:
+  - cli
+acceptance_criteria:
+  - "`partio sessions list` displays all sessions (active and ended) with session ID, agent, status, start time, and linked commit count"
+  - "`partio sessions info <session-id>` shows detailed session metadata including prompts, file touches, and checkpoint IDs"
+  - "`partio sessions stop <session-id>` transitions an ACTIVE session to ENDED state and cleans up state files"
+  - "All subcommands support `--json` flag for machine-readable output"
+  - "Commands work correctly in git worktree setups"
+pr_labels:
+  - minion
+---
+
+# Add `partio sessions` subcommands for session lifecycle management
+
+## Background
+
+Partio currently manages sessions internally through the hook lifecycle (pre-commit/post-commit), but provides no user-facing commands for inspecting or managing sessions. Users cannot list active sessions, inspect session details, or manually stop a stuck session.
+
+Inspired by entireio/cli's `entire sessions` subcommands (list, info, stop) added in v0.5.3.
+
+## What to implement
+
+Add a `partio sessions` command group with three subcommands:
+
+### `partio sessions list`
+- List all known sessions (active and ended) from `.partio/state/`
+- Show: session ID, agent type, status (ACTIVE/ENDED), start time, number of linked checkpoints
+- Support `--json` flag for scripting
+- Flag sessions that appear stale (ACTIVE but no activity for a configurable threshold)
+
+### `partio sessions info <session-id>`
+- Show full session metadata: agent, status, start/end time, prompts, files touched, checkpoint IDs
+- Support `--json` flag
+
+### `partio sessions stop <session-id>`
+- Transition a session from ACTIVE to ENDED
+- Clean up any leftover state files in `.partio/state/`
+- Useful for recovering from stuck sessions (e.g., agent crashed without cleanup)
+
+## Key files to examine
+- `internal/session/` — existing session domain types and state management
+- `internal/session/manager.go` — session lifecycle operations
+- `cmd/partio/` — existing command structure for reference

.minions/programs/ai-generated-checkpoint-summaries.md

@@ -0,0 +1,44 @@
+---
+id: ai-generated-checkpoint-summaries
+target_repos:
+  - cli
+acceptance_criteria:
+  - "partio explain --generate produces an AI-generated natural language summary of the checkpoint's session transcript"
+  - "The summary provider is configurable via partio settings (e.g., claude, local model)"
+  - "Summary generation has a configurable timeout (default 30s) to prevent indefinite hangs"
+  - "When no provider is configured, partio explain --generate prompts the user to select one"
+  - "Generated summaries are cached in checkpoint metadata so repeated calls don't re-generate"
+  - "partio explain without --generate continues to show the raw transcript as before"
+pr_labels:
+  - minion
+---
+
+# AI-generated checkpoint summaries with provider selection
+
+## Summary
+
+Add a `--generate` flag to `partio explain` that produces an AI-generated natural language summary of a checkpoint's session transcript. Support configurable summary providers and cache results to avoid redundant API calls.
+
+## Motivation
+
+Raw session transcripts can be long and hard to scan, especially for checkpoints with many turns or tool invocations. An AI-generated summary would:
+
+- Give reviewers a quick "what happened and why" for any checkpoint
+- Make checkpoint browsing more useful for team leads reviewing agent-assisted work
+- Complement the existing `partio explain` output with a higher-level narrative
+- Support `git log` integration where a one-line summary is more practical than a full transcript
+
+## Implementation Notes
+
+- Add `--generate` flag to the `explain` command in `cmd/partio/`
+- Create a summary provider interface in a new `internal/summary/` package
+- Implement a Claude Code provider that invokes the Claude CLI to generate summaries
+- Add a `summary_provider` setting to the config layer (`internal/config/`)
+- Apply a 30-second timeout (configurable) to summary generation to prevent hangs
+- Cache generated summaries in the checkpoint metadata on the orphan branch
+- When no provider is configured and `--generate` is used, prompt the user to select one
+- Keep summary generation fully optional — `partio explain` without `--generate` is unchanged
+
+## Source
+
+Inspired by entireio/cli#887 and entireio/cli#876 — adds summary provider selection for `explain --generate` and timeout protection for AI summary generation.

.minions/programs/always-write-model-metadata.md

@@ -0,0 +1,39 @@
+---
+id: always-write-model-metadata
+target_repos:
+  - cli
+acceptance_criteria:
+  - "Checkpoint metadata always includes a 'model' field, even when empty string"
+  - "The model JSON tag does not use omitempty"
+  - "Agent detection populates the model field when available from session data"
+  - "make test passes"
+  - "make lint passes"
+pr_labels:
+  - minion
+---
+
+# Always write model field to checkpoint metadata
+
+## Problem
+
+When checkpoint metadata is serialized, the model field may be omitted entirely if it is empty (due to `omitempty` on the JSON tag). This makes it harder for downstream consumers (dashboards, analytics) to distinguish between "model unknown" and "field missing" — they have to handle both a missing key and an empty value.
+
+## Solution
+
+Remove `omitempty` from the `Model` JSON struct tag in checkpoint metadata types so the field is always present in the serialized JSON (empty string when unknown, never missing). Additionally, ensure all agent detection code paths populate the model field when the information is available from session data.
+
+## Context
+
+- Inspired by entireio/cli#882
+- Relevant code: `internal/checkpoint/` (metadata types), `internal/agent/` (detection and model reporting)
+
+## Agents
+
+### implement
+
+```capabilities
+max_turns: 100
+checks: true
+retry_on_fail: true
+retry_max_turns: 20
+```

.minions/programs/auto-update-cli.md

@@ -0,0 +1,36 @@
+---
+id: auto-update-cli
+target_repos:
+  - cli
+acceptance_criteria:
+  - Global settings file supports an `auto_update` field with values `off` (default), `prompt`, or `auto`
+  - When a newer version is available, `partio` displays a notification with update instructions
+  - In `prompt` mode, partio asks Y/N before updating; in `auto` mode it updates silently
+  - `partio update [--check-only]` command runs the installer on demand
+  - Install provenance (method, timestamp) is recorded in the global config directory
+  - Dev builds skip update checks entirely
+pr_labels:
+  - minion
+---
+
+# Auto-update CLI behind opt-in global setting
+
+## Description
+
+Add an opt-in auto-update mechanism to the Partio CLI. When enabled via global settings (`~/.config/partio/settings.json`), the CLI checks for newer releases and either notifies, prompts, or silently updates depending on the configured mode.
+
+A new `partio update [--check-only]` command provides on-demand update capability regardless of the auto-update setting.
+
+## Why
+
+As Partio evolves — especially hook formats and checkpoint schemas — users running stale CLI versions encounter cryptic failures. An auto-update mechanism reduces support burden and ensures users benefit from bug fixes and new features without manual intervention.
+
+## Context hints
+
+- `internal/config/` — global settings loading
+- `cmd/partio/` — CLI command registration
+- `internal/config/defaults.go` — default config values
+
+## Source
+
+Inspired by entireio/cli PR #981 (auto-update feature behind opt-in global setting).

.minions/programs/auto-upgrade-stale-hooks.md

@@ -0,0 +1,44 @@
+---
+id: auto-upgrade-stale-hooks
+target_repos:
+  - cli
+acceptance_criteria:
+  - "`partio enable` compares installed hook content against expected content and updates hooks that differ"
+  - "Hooks that already match expected content are left untouched (no unnecessary writes)"
+  - "Backup chain is preserved — existing `.partio-backup` files are not overwritten during upgrade"
+  - "A message is printed when hooks are upgraded (e.g., 'Updated pre-commit hook')"
+  - "The `.partio/` directory existence check no longer short-circuits the entire enable flow"
+  - "Table-driven tests cover: fresh install, stale hook upgrade, already-current hook skip, and backup preservation"
+pr_labels:
+  - minion
+---
+
+# Auto-upgrade stale hooks on `partio enable`
+
+## Problem
+
+When a user upgrades the Partio CLI binary, the git hook scripts installed in their repositories become stale — they may reference old binary paths, use outdated shim logic, or miss new hooks added in later versions. Currently, `partio enable` short-circuits entirely when `.partio/` exists (`cmd/partio/enable.go:38-42`), telling the user "partio is already enabled" without checking whether the installed hooks are up to date.
+
+The only workaround is `partio disable && partio enable`, which users must know to do and which unnecessarily tears down and rebuilds state.
+
+## Desired behavior
+
+`partio enable` should detect stale hooks and silently upgrade them:
+
+1. If `.partio/` exists, skip directory/config creation but still check hooks.
+2. For each expected hook (`pre-commit`, `post-commit`, `pre-push`), read the installed script from the hooks directory (`git rev-parse --git-common-dir`).
+3. Compare the installed content against the expected content from `hookScript()` / `hookScriptAbsolute()` (`internal/git/hooks/hooks.go`).
+4. If the content differs, overwrite the hook file (preserving the existing backup chain — do not re-backup a partio-managed hook).
+5. If a hook is missing entirely (e.g., a new hook type added in a later version), install it following the normal backup logic.
+6. Print a summary of what was upgraded, or "partio is already enabled and hooks are up to date" if nothing changed.
+
+## Context hints
+
+- `cmd/partio/enable.go` — the `.partio/` existence check that needs to be relaxed
+- `internal/git/hooks/install.go` — `installHooks()` needs an upgrade-aware code path
+- `internal/git/hooks/hooks.go` — `hookScript()` / `hookScriptAbsolute()` generate expected content
+- `internal/git/hooks/uninstall.go` — backup restoration logic to preserve during upgrades
+
+## Source
+
+Inspired by entireio/cli PR #775 — OpenCode plugin hook rewrite when content differs.

.minions/programs/binary-file-detection-checkpoints.md

@@ -0,0 +1,34 @@
+---
+id: binary-file-detection-checkpoints
+target_repos:
+  - cli
+acceptance_criteria:
+  - "Binary files are detected and excluded from checkpoint tree objects"
+  - "Detection uses git's binary heuristic (NUL byte in first 8KB) or file extension matching"
+  - "Checkpoint metadata records which files were skipped as binary"
+  - "Existing checkpoints without binary detection remain readable"
+  - "make test passes with binary detection tests"
+  - "make lint passes"
+pr_labels:
+  - minion
+---
+
+# Detect and skip binary files in checkpoint tree writes
+
+Add binary file detection to prevent large binary blobs from being written into checkpoint tree objects.
+
+## What to implement
+
+1. **Binary detection** — before writing file blobs to the checkpoint tree via git plumbing (hash-object, mktree), check if the file content is binary using git's standard heuristic (presence of NUL bytes in the first 8KB)
+2. **Skip and record** — exclude detected binary files from the tree object and record the skipped paths in checkpoint metadata
+3. **Configurable allowlist** — optionally allow users to configure file extensions that should always be included or excluded via the config system
+
+## Why this matters
+
+When agent sessions modify or create binary files (images, compiled artifacts, database files), these get written into checkpoint tree objects on the orphan branch. This unnecessarily inflates the git object database and slows push operations. Binary content provides no useful context for understanding the reasoning behind code changes.
+
+## Context hints
+
+- `internal/checkpoint/` — checkpoint storage using git plumbing
+- `internal/git/` — git operations
+- `internal/config/` — configuration system for allowlist settings