rdmpw3275m-changelog-20260921-1334-resolve-feat-20260905-14-worktree-checkpoint-production-wiring

Summary: Wired the git worktree isolation and ephemeral checkpoint engine (ECSWorktreeManager, aliased as TyrellWorktreeEngine / CheckpointEngine) to production callers across tyrelld HTTP lease API, turn boundary checkpointing with zero staging pollution, FleetChatView 1-click turn revert, and orchestrator orphan snapshotting, resolving FEAT-20260905-14.

• Host: rdmpw3275m (work authored in linked worktree and integrated on canonical hub rdmsm4x)
• Ticket: FEAT-20260905-14 (RESOLVED)
• Parent Epic: EPIC-20260905-01 (T3code Apple-Native Adaptation)
• Related Tickets: FEAT-20260903-02

1. Scope & Architecture Changes

1. Reconciled Naming & Typealiases (Sources/TyrellCore/Worktree/WorktreeModels.swift):

   • Reconciled FEAT-20260903-02 and FEATURE_MATRIX.md specifications with ECSWorktreeManager by declaring:

     public typealias TyrellWorktreeEngine = ECSWorktreeManager
     public typealias CheckpointEngine = ECSWorktreeManager

   • Added strongly-typed Codable request/response models:
     • AllocateWorktreeRequest
     • ReleaseWorktreeRequest
     • ReleaseWorktreeResponse
     • CaptureCheckpointRequest
     • RestoreCheckpointRequest
     • RestoreCheckpointResponse
     • SnapshotOrphanRequest
     • WorktreeDiffResponse
     • WorktreeAPIError

2. Worktree Lease API on tyrelld (Sources/tyrelld/WorktreeRoutes.swift, Daemon.swift):

   • Registered endpoints under /api/worktrees/* secured by ServerLogic.authorized:
     • GET /api/worktrees: lists all active worktrees.
     • POST /api/worktrees/allocate: allocates an isolated worktree under ~/.tyrell/worktrees with merge-base anchoring and submodule updates.
     • POST /api/worktrees/release: decrements refCount and purges worktree from disk when 0.
     • POST /api/worktrees/checkpoint: out-of-band turn boundary checkpoint into refs/tyrell/checkpoints/<session>/<turn>.
     • POST /api/worktrees/restore: atomic restore via git restore --worktree --staged and git clean -fd.
     • GET /api/worktrees/diff: returns unified diff between checkpoint commits or working tree.
     • POST /api/worktrees/snapshot-orphan: snapshots an orphan dirty worktree.

3. Turn Boundary Checkpointing & Staging Preservation (Sources/TyrellCore/Worktree/ECSWorktreeManager.swift):

   • Added sanitizeGitRefComponent(_:) adhering strictly to git ref formatting rules (sanitizing colons :, spaces, ~, ^, ?, *, [, ], \, .., @{), guaranteeing real conversation identifiers like domain:tyrell.local:general succeed during git update-ref.
   • Verified that captureCheckpoint uses an isolated GIT_INDEX_FILE, guaranteeing that the developer's .git/index is byte-identical before and after checkpoint capture (verified via SHA256 comparison).

4. 1-Click Turn Revert in GUI (Sources/tyrell-app/ChatViewModel.swift, FleetChatView.swift):

   • ChatViewModel:
     • Added @Published var activeWorktreeURL: URL?, checkpointsByTurn, checkpointsByMessageID, lastRestoredCommitOID, and revertNotice.
     • Added captureTurnCheckpoint(messageID:turnIndex:worktreeManager:), automatically invoked at turn boundaries when sending messages with an active worktree.
     • Added revertCheckpoint(_:worktreeManager:) and revertTurn(for:worktreeManager:) performing atomic rollback and state updates.
   • FleetChatView:
     • Added 1-click turn revert button (arrow.uturn.backward.circle.fill) to ChatMessageRow for any turn with an associated checkpoint.
     • Added feedback banner with dismiss affordance when a turn is reverted.

5. Orchestrator Orphan Dirty Worktree Snapshotting (Sources/TyrellCore/Approvals/SessionHoldOrchestrator.swift):

   • Added snapshotOrphanDirtyWorktree(worktreeURL:sessionID:reason:worktreeManager:) on SessionHoldOrchestrator and snapshotOrphanWorktree on ECSWorktreeManager, replacing external worktree_snapshot.zsh save calls per PRD §4.3 Rule 3.

6. Documentation & Capability Status Matrix (FEATURE_MATRIX.md, SESSION-STATE.md):

   • Updated FEATURE_MATRIX.md marking FEAT-20260903-02 / FEAT-20260905-14 as Shipped with full implementation subsystem links and verification evidence.
   • Recorded checkpoint in SESSION-STATE.md.

2. Verification Evidence & Test Execution

• Tests/TyrellCoreTests/WorktreeLeaseAndCheckpointIntegrationTests.swift (NEW):
  1. testTypealiasesAndPayloadSerialization: Verified TyrellWorktreeEngine & CheckpointEngine aliases and payload round-trips.
  2. testTurnBoundaryCheckpointDoesNotAlterDeveloperIndex: Verified out-of-band index isolation (GIT_INDEX_FILE), proving SHA256 of .git/index is byte-identical before and after checkpoint capture.
  3. testBidirectionalRollbackRestorationAndCorruptCommitRejection: Verified both directions (successful rollback restores exact file contents and purges rogue files, while bogus commit OID throws WorktreeError.commandFailed rather than silently succeeding).
  4. testOrphanDirtyWorktreeSnapshottingViaCheckpointEngine: Verified orchestrator snapshotting into hidden checkpoint refs.
  5. testFullAllocateCheckpointCorruptRestoreReleaseLifecycle: Verified full end-to-end lifecycle.
  6. testDefaultWorktreeRootLocationAndLeaseAllocation: Verified allocation under ~/.tyrell/worktrees.
• Tests/tyrell-appTests/ChatTurnCheckpointTests.swift (NEW):
  • Verified ChatViewModel turn checkpointing and 1-click revert.
• Full regression suite execution:
  • WorktreeEngineTests: 11/11 tests passed.
  • WorktreeLeaseAndCheckpointIntegrationTests: 6/6 tests passed.
  • ChatTurnCheckpointTests: 1/1 test passed.
  • AgentsRosterLiveTelemetryTests: 6/6 tests passed.
  • ChatStreamAdoptionTests: 5/5 tests passed.
  • Total Worktree & App test suites passing: 36 tests across 5 suites.

3. Git Integration & Delivery

• Integrated into canonical repository rdmsm4x:~/dev/apps/Tyrell on main:
  • Feature commit: 272e5d5
  • Session state commit: 4036565
• Pushed to both remotes:
  • fleet (git.ecs0.net:git/apps/Tyrell.git)
  • backup (github.com/richhdoty/rdmsm4x-dev-apps-tyrell.git)
• Ticket FEAT-20260905-14 resolved via ~/bin/ticket resolve.
• Fleet message bus broadcast sent: 20260921-133333-FA8A39EF.