feat(mol): Add session wisps for crew and polecat workers (gt-9g82)

Introduces Proto → Wisp → Mol architecture for agent sessions: - mol-crew-session: Light harness enabling autonomous overnight work Key insight: if attached mol exists, continue without awaiting input - mol-polecat-session: One-shot wisp wrapping polecat work assignments Handles onboard → execute → cleanup lifecycle This separates "how to work" (proto) from "what to work on" (mol), enabling session continuity and autonomous long-mol processing. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-22 16:08:40 -08:00
parent 7a8675255b
commit b71c188cfb
2 changed files with 560 additions and 0 deletions
--- a/internal/beads/builtin_molecules.go
+++ b/internal/beads/builtin_molecules.go
@@ -20,6 +20,8 @@ func BuiltinMolecules() []BuiltinMolecule {
 		VersionBumpMolecule(),
 		DeaconPatrolMolecule(),
 		RefineryPatrolMolecule(),
+		CrewSessionMolecule(),
+		PolecatSessionMolecule(),
 	}
 }

@@ -900,6 +902,230 @@ Needs: context-check`,
 	}
 }

+// CrewSessionMolecule returns the crew-session molecule definition.
+// This is a light harness for crew workers that enables autonomous overnight work.
+// Key insight: if there's an attached mol, continue working without awaiting input.
+func CrewSessionMolecule() BuiltinMolecule {
+	return BuiltinMolecule{
+		ID:    "mol-crew-session",
+		Title: "Crew Session",
+		Description: `Light session harness for crew workers.
+
+This molecule enables autonomous work on long-lived molecules. The key insight:
+**If there's an attached mol, continue working without awaiting input.**
+
+This transforms crew workers from interactive assistants to autonomous workers
+that can churn through long molecules overnight.
+
+## Step: orient
+Load context and identify self.
+
+` + "```" + `bash
+gt prime                    # Load Gas Town context
+` + "```" + `
+
+Identify yourself:
+- Read crew.md for role context
+- Note your rig and crew member name
+- Understand the session wisp model
+
+## Step: handoff-read
+Check inbox for predecessor handoff.
+
+` + "```" + `bash
+gt mail inbox
+` + "```" + `
+
+Look for 🤝 HANDOFF messages from your previous session.
+If found:
+- Read the handoff carefully
+- Load predecessor's context and state
+- Note where they left off
+
+If no handoff found, this is a fresh start.
+Needs: orient
+
+## Step: check-attachment
+Look for pinned work to continue.
+
+` + "```" + `bash
+bd list --pinned --assignee=$(gt whoami) --status=in_progress
+gt mol status
+` + "```" + `
+
+**DECISION POINT:**
+
+If attachment found:
+- This is autonomous continuation mode
+- Proceed directly to execute step
+- NO human input needed
+
+If no attachment found:
+- This is interactive mode
+- Await user instruction before proceeding
+- Mark this step complete when user provides direction
+Needs: handoff-read
+
+## Step: execute
+Work the attached molecule.
+
+Find next ready step in the attached mol:
+` + "```" + `bash
+bd ready --parent=<work-mol-root>
+bd update <step> --status=in_progress
+` + "```" + `
+
+Work until one of:
+- All steps in mol completed
+- Context approaching limit (>80%)
+- Natural stopping point reached
+- Blocked by external dependency
+
+Track progress in the mol itself (close completed steps).
+File discovered work as new issues.
+Needs: check-attachment
+
+## Step: cleanup
+End session with proper handoff.
+
+1. Sync all state:
+` + "```" + `bash
+git add -A && git commit -m "WIP: <summary>" || true
+git push origin HEAD
+bd sync
+` + "```" + `
+
+2. Write handoff to successor (yourself):
+` + "```" + `bash
+gt mail send <self-addr> -s "🤝 HANDOFF: <brief context>" -m "
+## Progress
+- Completed: <what was done>
+- Next: <what to do next>
+
+## State
+- Current step: <step-id>
+- Blockers: <any blockers>
+
+## Notes
+<any context successor needs>
+"
+` + "```" + `
+
+3. Session ends. Successor will pick up from handoff.
+Needs: execute`,
+	}
+}
+
+// PolecatSessionMolecule returns the polecat-session molecule definition.
+// This is a one-shot session wisp that wraps polecat work.
+// Unlike patrol wisps (which loop), this wisp terminates with the session.
+func PolecatSessionMolecule() BuiltinMolecule {
+	return BuiltinMolecule{
+		ID:    "mol-polecat-session",
+		Title: "Polecat Session",
+		Description: `One-shot session wisp for polecat workers.
+
+This molecule wraps the polecat's work assignment. It handles:
+1. Onboarding - read polecat.md, load context
+2. Execution - run the attached work molecule
+3. Cleanup - sync, burn, request shutdown
+
+Unlike patrol wisps (which loop), this wisp terminates when work is done.
+The attached work molecule is permanent and auditable.
+
+## Step: orient
+Read polecat.md protocol and initialize context.
+
+` + "```" + `bash
+gt prime               # Load Gas Town context
+bd sync --from-main    # Fresh beads state
+gt mail inbox          # Check for work assignment
+` + "```" + `
+
+Understand:
+- Your identity (rig/polecat-name)
+- The beads system
+- Exit strategies (COMPLETED, BLOCKED, REFACTOR, ESCALATE)
+- Handoff protocols
+
+## Step: handoff-read
+Check for predecessor session handoff.
+
+If this polecat was respawned after a crash or context cycle:
+- Check mail for 🤝 HANDOFF from previous session
+- Load state from the attached work mol
+- Resume from last completed step
+
+` + "```" + `bash
+gt mail inbox | grep HANDOFF
+bd show <work-mol-id>  # Check step completion state
+` + "```" + `
+Needs: orient
+
+## Step: find-work
+Locate attached work molecule.
+
+` + "```" + `bash
+gt mol status          # Shows what's on your hook
+` + "```" + `
+
+The work mol should already be attached (done by spawn).
+If not attached, check mail for work assignment.
+
+Verify you have:
+- A work mol ID
+- Understanding of the work scope
+- No blockers to starting
+Needs: handoff-read
+
+## Step: execute
+Run the attached work molecule to completion.
+
+For each ready step in the work mol:
+` + "```" + `bash
+bd ready --parent=<work-mol-root>
+bd update <step> --status=in_progress
+# ... do the work ...
+bd close <step>
+` + "```" + `
+
+Continue until reaching the exit-decision step in the work mol.
+All exit types (COMPLETED, BLOCKED, REFACTOR, ESCALATE) proceed to cleanup.
+
+**Dynamic modifications allowed**:
+- Add review or test steps if needed
+- File discovered blockers as issues
+- Request session refresh if context filling
+Needs: find-work
+
+## Step: cleanup
+Finalize session and request termination.
+
+1. Sync all state:
+` + "```" + `bash
+bd sync
+git push origin HEAD
+` + "```" + `
+
+2. Update work mol based on exit type:
+   - COMPLETED: ` + "`bd close <work-mol-root>`" + `
+   - BLOCKED/REFACTOR/ESCALATE: ` + "`bd update <work-mol-root> --status=deferred`" + `
+
+3. Burn this session wisp (ephemeral, no audit needed):
+` + "```" + `bash
+bd mol burn
+` + "```" + `
+
+4. Request shutdown from Witness:
+` + "```" + `bash
+gt mail send <rig>/witness -s "SHUTDOWN: <polecat-name>" -m "Session complete. Exit: <type>"
+` + "```" + `
+
+5. Wait for Witness to terminate session. Do not exit directly.
+Needs: execute`,
+	}
+}
+
 // SeedBuiltinMolecules creates all built-in molecules in the beads database.
 // It skips molecules that already exist (by title match).
 // Returns the number of molecules created.