pi-crew 0.2.3 → 0.2.5

package/skills/git-master/SKILL.md

@@ -1,24 +1,225 @@
----
-name: git-master
-description: Commit and release hygiene for safe version-control work. Use when preparing commits, releases, version bumps, publishing, or validating package installation.
----
-
-# git-master
-
-Use this skill for commit/release hygiene.
-
-## Commit rules
-
-- Check `git status --short` before staging.
-- Stage only files related to the current task.
-- Keep commits independently revertible.
-- Use concise imperative commit messages.
-- Do not push or publish unless explicitly requested.
-- Do not include secrets, OTPs, local temp files, or generated tarballs.
-
-## Release rules
-
-- Run the required verification gate before version bumps.
-- Bump version only after tests pass and user confirms publish intent.
-- Verify registry after publish with `npm view`.
-- Install through `pi install npm:pi-crew` when validating Pi package loading.
+---
+name: git-master
+description: Commit and release hygiene for safe version-control work. Use when preparing commits, releases, version bumps, publishing, or validating package installation.
+---
+
+# git-master
+
+Use this skill for commit/release hygiene. This skill covers git workflow from local changes to published releases.
+
+## Pre-commit Checklist
+
+Before every commit:
+
+1. Run `git status --short` — understand what changed
+2. Stage only files related to the current task
+3. Review staged diff with `git diff --staged`
+4. Check for unintended changes (generated files, temp files, secrets)
+5. Ensure tests pass locally before committing
+
+## Commit Rules
+
+- **Independent commits**: Each commit should be self-contained and revertible. Don't mix unrelated changes.
+- **Concise messages**: Use imperative mood, 50 chars or less for subject. Add body for context.
+- **Format**: `type(scope): subject` where type is `fix`, `feat`, `chore`, `docs`, `test`, `refactor`
+- **Do not include**: secrets, OTPs, local temp files, `node_modules`, `dist/`, `*.log`, `*.tmp`
+- **Do not push/publish** unless explicitly requested
+- **Verify** before staging large generated files (tarballs, build outputs)
+
+## Commit Message Format
+
+```
+type(scope): short description (50 chars max)
+
+ Longer description if needed. Explain WHY the change was made,
+ not just what changed. Reference issues/PRs if applicable.
+
+Refs: #123
+```
+
+**Examples:**
+```
+fix(live-agent): prevent cross-workspace agent access
+feat(widget): add snapshot cache with 500ms TTL
+docs(skills): add event-log-tracing skill
+chore(tests): add integration test for reconcileAllStaleRuns
+```
+
+## Branch Naming
+
+| Pattern | Use case | Example |
+|---|---|---|
+| `fix/<description>` | Bug fixes | `fix/ghost-run-display` |
+| `feat/<description>` | New features | `feat/skill-templates` |
+| `docs/<description>` | Documentation | `docs/skills-deep-research` |
+| `chore/<description>` | Tooling, CI | `chore/update-ci-node22` |
+| `hotfix/<description>` | Urgent production fixes | `hotfix/secret-leak` |
+
+## Rollback Procedures
+
+### Revert last commit (safe, keeps history)
+```bash
+git revert HEAD
+git push
+```
+
+### Reset to known-good state (rewrites history)
+```bash
+# Soft: keep changes staged
+git reset --soft HEAD~1
+
+# Mixed: keep changes unstaged
+git reset HEAD~1
+
+# Hard: discard all changes (DESTRUCTIVE)
+git reset --hard <commit-hash>
+```
+
+### Checkout single file from a past commit
+```bash
+git checkout <commit-hash> -- path/to/file
+```
+
+### Recover from a bad reset
+```bash
+git reflog  # find the commit before reset
+git reset --hard <reflog-entry>
+```
+
+## Regression Hunting with git bisect
+
+When a regression is found and the culprit commit is unknown:
+
+```bash
+git bisect start
+git bisect bad              # current commit is bad
+git bisect good <known-good> # a commit that worked
+
+# git checks out a middle commit
+# test it: if bad, mark it; if good, mark it
+# repeat until culprit found
+git bisect bad   # or: git bisect good
+
+# after bisect completes:
+git bisect reset  # return to original branch
+
+# culprit is the first bad commit in the range
+```
+
+## Amend and Force-Push
+
+### Amend last commit (before push)
+```bash
+# Make additional changes
+git add .
+git commit --amend --no-edit  # amend without changing message
+git commit --amend -m "new message"  # or with new message
+```
+
+### Force-push (DESTRUCTIVE — only when necessary)
+```bash
+# Only force-push to feature branches, never main/master
+git push --force-with-lease origin <branch>
+
+# --force-with-lease is safer: fails if someone else pushed
+# Regular --force can overwrite others' work
+```
+
+**When safe to force-push:**
+- Your feature branch that only you use
+- After `git rebase` (rebase rewrites commit history)
+- After amending commits not yet pushed
+
+**When to NEVER force-push:**
+- Shared branches (main, master, develop)
+- Branch with active PR
+- Branch others may have based work on
+
+## Tag and Release
+
+### Create a version tag
+```bash
+git tag -a v1.2.3 -m "Release 1.2.3: Add skill templates"
+git push origin v1.2.3
+```
+
+### Tag after version bump
+```bash
+git add CHANGELOG.md package.json
+git commit -m "chore: bump version to 1.2.3"
+git tag -a 1.2.3 -m "Version 1.2.3"
+git push && git push --tags
+```
+
+### List and verify tags
+```bash
+git tag -l
+git show <tag-name>
+```
+
+## Version Bump Sequence
+
+1. Verify: `npx tsc --noEmit` passes
+2. Verify: `npm test` passes
+3. Update `CHANGELOG.md` with changes for this version
+4. Update `package.json` version field
+5. Commit: `chore: bump version to X.Y.Z`
+6. Tag: `git tag -a X.Y.Z -m "Release X.Y.Z"`
+7. Publish: `npm publish --access public`
+8. Verify: `npm view pi-crew` shows new version
+
+## Stash Patterns
+
+### Stash work-in-progress
+```bash
+git stash -u           # include untracked files
+git stash push -m "WIP: feature X"  # with message
+```
+
+### Apply and manage stashes
+```bash
+git stash list         # show all stashes
+git stash pop          # apply latest and remove
+git stash apply         # apply latest, keep in stash
+git stash apply stash@{2}  # apply specific stash
+git stash drop          # remove latest stash
+git stash clear         # remove all stashes
+```
+
+## Anti-patterns
+
+- **Committing generated files**: Don't commit `dist/`, `build/`, `*.min.js` unless intentional
+- **Large commits**: If >500 lines changed, consider splitting
+- **Committing with unverified tests**: Run tests before commit
+- **Force-pushing main/master**: Never
+- **Committing secrets**: Check for `API_KEY`, `TOKEN`, `PASSWORD`, `SECRET` before staging
+- **Unclear messages**: "fix stuff" is not a valid commit message
+
+---
+
+## Source patterns
+
+- `src/state/atomic-write.ts` — atomic git-safe file writes
+- `src/worktree/worktree-manager.ts` — worktree git operations
+- `src/utils/conflict-detect.ts` — git conflict detection
+- `package.json` — version field, publish scripts
+
+---
+
+## Verification
+
+```bash
+cd pi-crew
+git status --short
+git log --oneline -5
+git diff --staged --stat
+
+# TypeScript
+npx tsc --noEmit
+
+# Tests
+npm test
+
+# Package dry-run before publish
+npm pack --dry-run
+```

package/skills/live-agent-lifecycle/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: live-agent-lifecycle
+description: Live agent registration, workspace isolation, termination, and eviction workflow. Use when tracking live agents, debugging ghost agents, or understanding workspace boundaries.
+---
+
+# live-agent-lifecycle
+
+Live agents are real-time, in-memory worker sessions managed by `LiveAgentManager` (`src/runtime/live-agent-manager.ts`). They are distinct from `CrewAgentRecord` files on disk — live agents provide real-time activity (tool names, response text, turn count) while agent records are durable snapshots.
+
+## Architecture
+
+**LiveAgentHandle** is the core data structure:
+
+```typescript
+interface LiveAgentHandle {
+  agentId: string;        // unique per run
+  taskId: string;         // maps to task
+  runId: string;          // run this agent belongs to
+  workspaceId: string;   // manifest.cwd — workspace boundary
+  role?: string;
+  agent?: string;
+  modelName?: string;
+  session: LiveSessionHandle; // steer/prompt/abort/dispose
+  status: CrewAgentRecord["status"];
+  pendingSteers: string[];
+  pendingFollowUps: string[];
+  pendingMessages: IrcMessage[];
+  activity: LiveAgentActivity; // real-time tracking
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+The in-memory `liveAgents` Map stores all active handles. It is never persisted — on Pi restart, the Map is empty and agents are re-created from agent records.
+
+---
+
+## Registration
+
+`registerLiveAgent(input, eventLogFn?, eventsPath?)` is called when a live session worker starts. It:
+
+1. Creates or reuses the handle in `liveAgents` Map
+2. Preserves pending steers/followups from previous sessions
+3. Emits `live_agent.registered` event to events.jsonl
+4. Flushes any pending steers/followups immediately if the session already has the methods
+
+Key caller sites:
+- `live-session-runtime.ts` — when a live session agent starts
+- `live-executor.ts` — when spawning a live task
+- (workspaceId is passed through the entire call chain)
+
+---
+
+## Workspace Isolation
+
+**`workspaceId: string`** field is the workspace boundary. Set to `manifest.cwd` at registration time.
+
+**Why it matters:** When Pi has multiple workspace folders open, agents from workspace A must not be visible or controllable from workspace B. Every handle carries its origin workspace.
+
+**Enforcement in api.ts:**
+- `listActiveLiveAgentsByWorkspace(workspaceId)` — filters by workspace
+- Steering/follow-up operations check `live.workspaceId !== manifest.cwd` → reject with error
+- Widget queries use `listLiveAgentsByWorkspace(manifest.cwd)` so each workspace only sees its own agents
+
+**Enforcement in live-session-runtime.ts:**
+- Config carries `workspaceId` from `TeamContext.workspaceId`
+- Session creation passes workspaceId through
+
+---
+
+## Activity Tracking
+
+`LiveAgentActivity` provides real-time data without reading disk:
+
+```typescript
+interface LiveAgentActivity {
+  activeTools: Map<string, string>;   // toolName → description
+  toolUses: number;                   // total invocations
+  turnCount: number;
+  maxTurns?: number;
+  responseText: string;               // last 200 chars
+  compactionCount: number;
+  startedAtMs: number;
+  completedAtMs: number;              // 0 = still running
+  modelName?: string;
+}
+```
+
+Tracking functions (called from live-executor):
+- `trackLiveAgentToolStart(agentId, toolName)` — adds tool to activeTools
+- `trackLiveAgentToolEnd(agentId, toolName)` — removes tool from activeTools
+- `trackLiveAgentTurnEnd(agentId, compaction?)` — increments turn, clears tools
+- `trackLiveAgentResponseText(agentId, text)` — stores last 200 chars
+- `markLiveAgentCompleted(agentId)` — sets completedAtMs
+
+---
+
+## Termination
+
+`terminateLiveAgent(agentIdOrTaskId, status?, eventLogFn?, eventsPath?)` is the canonical termination path:
+
+1. Sets handle status (default: "stopped")
+2. Emits `live_agent.terminated` event to events.jsonl
+3. Calls `session.abort()` to stop the child
+4. Calls `session.dispose()` to clean up
+5. Removes from `liveAgents` Map
+
+**Termination call sites (4 total):**
+
+| Location | When |
+|---|---|
+| `team-runner.ts` (run complete) | All agents terminated when run succeeds or fails |
+| `team-runner.ts` (task complete) | Per-task termination when `terminateOnTaskComplete=true` |
+| `background-runner.ts` (catch) | Termination in finally block after background run |
+| `cancel.ts` | Termination when user cancels a run |
+| `respond.ts` | Termination when responding to waiting tasks |
+| `crash-recovery.ts` (purgeStale) | Termination when cleaning up orphaned runs |
+| `crash-recovery.ts` (reconcile) | Termination when reconciling stale runs |
+
+`terminateLiveAgentsForRun(runId, status?, eventLogFn?, eventsPath?)` terminates all agents for a run in parallel.
+
+---
+
+## Eviction
+
+**Stale handles** are handles whose status is terminal (not running/queued/waiting) and older than 10 minutes. `evictStaleLiveAgentHandles(now?)` removes them:
+
+```typescript
+const STALE_HANDLE_MS = 10 * 60 * 1000;
+// Only evict terminal-status handles
+if (handle.status !== "running" && handle.status !== "queued" && handle.status !== "waiting") {
+  const age = now - new Date(handle.updatedAt).getTime();
+  if (age > STALE_HANDLE_MS) {
+    liveAgents.delete(agentId);
+    safeDisposeLiveSession(handle);
+  }
+}
+```
+
+**Triggered on every widget refresh** in `crew-widget.ts`:
+```typescript
+evictStaleLiveAgentHandles(); // called at start of activeWidgetRuns()
+```
+
+This prevents the Map from growing indefinitely with completed agents.
+
+---
+
+## Live Agent → Agent Record Sync
+
+On task completion, `upsertCrewAgent(manifest, recordFromTask(manifest, task, "live-session"))` is called to persist the final status to disk (`agents.json`, `agents/<id>/status.json`). This ensures the widget sees the correct status even after the live agent handle is evicted.
+
+The sync chain:
+```
+task.completed → upsertCrewAgent → agents.json updated
+             → live_agent.terminated event logged
+             → (later) evictStaleLiveAgentHandles → handle removed from Map
+```
+
+---
+
+## Anti-patterns
+
+- **Missing termination on error path**: If a live agent crashes and `terminateLiveAgent` is not called, the handle stays in the Map forever with status "running". Use `finally` blocks or crash-recovery to ensure termination.
+- **Stale handle accumulation**: Without `evictStaleLiveAgentHandles`, completed agents accumulate in the Map. This is mitigated by calling eviction on every widget refresh.
+- **Cross-workspace access**: Never call steer/follow-up/stop/resume on a handle whose `workspaceId` differs from the current workspace. Always check `live.workspaceId === manifest.cwd`.
+- **Losing activity on session switch**: Live agents are in-memory only. On Pi session switch/restart, all activity tracking is lost. Agent records on disk persist.
+
+---
+
+## Source patterns
+
+- `src/runtime/live-agent-manager.ts` — register, terminate, evict, workspaceId
+- `src/runtime/live-session-runtime.ts` — 4 lifecycle gaps fixed
+- `src/runtime/team-runner.ts` — terminate on success/fail
+- `src/runtime/background-runner.ts` — terminate on catch
+- `src/runtime/crash-recovery.ts` — terminate in purge+reconcile
+- `src/extension/team-tool/api.ts` — workspaceId filter
+- `src/extension/team-tool/cancel.ts` — terminate on cancel
+- `src/extension/team-tool/respond.ts` — terminate on respond
+- `src/ui/crew-widget.ts` — evictStaleLiveAgentHandles on refresh
+
+---
+
+## Verification
+
+```bash
+cd pi-crew
+npx tsc --noEmit
+node --experimental-strip-types --test test/unit/live-agent-manager.test.ts test/unit/live-session-runtime.test.ts test/unit/live-agent-control.test.ts
+npm test
+```