[rawphp]

Closes #16

Contract

• done: start() takes a claimed issue to a launched /factory session as softfac's runner/start.rs does: findProject(repo.path) before the claim; the launch-sending step once; the launch under softfac:<run>:launch with softfac's title, base, first message and the machine's model; the session_launched line; the issue text checked again once the session exists (a change archives the session, removes its worktree and goes stuck); the approval-rechecked step; the building label, the status comment and the state_changed line; outcome { started, run, threadId }. Every resume path replays from the ledger, and the pass calls start again for a confirmed run still in triage. A refused launch goes stuck with the detail and the session-may-exist note in the ledger only.
• out: resume from an earlier run's branch, owed feedback, abandoning a closed issue, archiving older runs in finishOlderRuns (Building: follow the session to its result line #17–End of a run: merge, close, abandon and stop by hand #20), Linear.
• risk: none
• test: vp test run apps/server/src/factory → pass; vp run --filter t3 typecheck → pass

Acceptance criteria

• A run in factory:triage finds the T3 project by the repo's path; a missing project makes the run stuck with softfac's reason, and no project is created — start.test.ts "a repo with no T3 project goes stuck before any launch is sent" (reason no T3 project for this repo on this machine, public comment the factory could not launch a session) and "a T3 that cannot be reached when the project is looked up claims nothing".
• It launches with command id softfac:<run>:launch, the base from the factory block, softfac's thread title and first message, and the model instance and model from the machine config — start.test.ts "claims, launches the session and moves the issue to building" (asserts the whole LaunchRequest), "records the model the launch call sent"; messages.test.ts pins the first message byte for byte against softfac's launch_message.
• It checks the issue text again and acts on a change as softfac does — start.test.ts "a text that changed before the second look archives the session and goes stuck" (changed and unjudged), "the second look comes after the launch is recorded and before the label", "an archive that fails is an error before anything is written, and the next start retries".
• It sets factory:building, upserts the status comment and writes session_launched with the thread id — the happy-path test's tracker calls and ledger lines (startedEvents()).
• A crash between launch and record is safe: the next pass launches with the same command id and gets the same thread — start.test.ts "writes the launch-sending step once and sends under the same command id", "with no session launches and then looks at the text once"; pass.test.ts "a confirmed triage run gets start on the next pass, and the line says the session started".
• softfac's runner tests "start" and "start: a claim that errors after GitHub applied it" are ported and pass — start.test.ts describes "start: a fresh ready issue", "start: a claim call that fails", "start: a launch that an earlier pass may have sent", "start: a resume", "start: older runs of the issue".

Decisions

• The issue body says the text is checked "before launching"; softfac checks it right after the launch is recorded and before the label moves to building, and never before the launch (a resume that skipped the launch for a changed text would leave an untracked thread running). The port follows softfac and the ported tests.
• In-process there is no transient launch failure class (no connection, no timeout, no unreadable reply): every failure of FactorySessions.launch is T3's answer after the request went out, so it is final and recorded with the session-may-exist note. A findProject failure still fails the start with nothing claimed, as in softfac.
• FactorySessions.layerLive (adapter) provides the projection store the server does not have in scope where the factory is merged in; nothing outside factory/ changed.
• The factory's worktree was cut from a stale base (e4bcce9f6); it was fast-forwarded to origin/main (a8a24e261) before provisioning. No factory:* labels were created; all seven existed.

Gate

• vp test run apps/server/src/factory → exit 0 (31 files, 921 tests)
• vp run --filter t3 typecheck → exit 0

Models

• maker: claude-sonnet-5-5
• checker: claude-opus-5-5

Review

• cycles: 2
• fixed: cycle 1 (correctness, reliability, maintainability): the pass never called start again for a confirmed triage run, so a start cut short after the launch left its session untracked (blocker, pass.ts workRuns); a failed T3 call was logged as kind ledger instead of t3; the stuck path, session stop and finishBuilding moved to runner/run.ts with the step on Progress so Building: follow the session to its result line #17/Gating: a passing gate opens the PR for review, a failing one goes back to the session #19/End of a run: merge, close, abandon and stop by hand #20 reuse them; the ledger step names are spelled once. Cycle 2 (testing, mutation): 12/12 named mutants killed; two assertions tightened.
• leftovers: none

Lessons

• A command guard can match prose the contract requires. Symptom: the maker stopped at its first edit because the machine's Bash deny hook matched gh auth token inside a heredoc that wrote the launch message, which forbids that very command. Cause: the guard scans command lines, and the contract text carried the phrase as data. Default: when a packet's byte-exact text contains words a command guard watches, say in the packet to write those files through the Write/Edit tools and never put the phrase on a command line.
• A criterion that says "the next pass does X" names a caller; put the caller in files. Symptom: correctness approved the runner, and reliability found that nothing in the pass ever called it again, so the crash-safety criterion was unreachable in production. Cause: the port split the step (start.rs) from its dispatcher (tick.rs) and the contract named only the step. Default: for each criterion phrased as "the next pass/run/tick does X", list the dispatcher in files: and add a test that drives X through it.

Commits

• 24d132e34 feat(factory): a sessions layer with its projection store provided — Make slice
• 844104c4a test: port softfac's start tests for the launch — Make slice (red)
• cb7c29f67 feat(factory): launch the /factory session for a claimed issue — Make slice
• d38718702 test(factory): a confirmed triage run is started again by the next pass — Check cycle 1 (red)
• 76c9b3659 fix(factory): the pass starts a confirmed triage run again — Check cycle 1
• c20e7a48a test(factory): a start that fails at T3 is logged as a t3 error — Check cycle 1 (red)
• 13207bed2 fix(factory): a failed T3 call is logged as kind t3 — Check cycle 1
• 8e61acc4c refactor(factory): move the run's stop and stuck path to runner/run.ts — Check cycle 1 (no red phase: a move)
• 9f46619cd test(factory): pin the whole outcome in two stuck-path start tests — Check cycle 2 (no red phase: tightened assertions)

Files

• apps/server/src/factory/runner/start.ts — the launch, the second look and the move to building; findProject before the claim; resume from the ledger
• apps/server/src/factory/runner/run.ts — new: Progress, goStuck (with the session stop and worktree removal) and finishBuilding, shared by the steps to come
• apps/server/src/factory/runner/messages.ts — the launch message, LAUNCH_FAILED, TEXT_CHANGED, the session-may-exist note
• apps/server/src/factory/runner/progress.ts — Seen reads launch-sending, approval-rechecked, the worktree and its removal
• apps/server/src/factory/pass.ts — workRuns calls start for confirmed triage runs; started outcome; T3 errors are kind t3
• apps/server/src/factory/index.ts — wires FactorySessions into start; FactoryLayer provides layerLive
• apps/server/src/factory/t3/sessions.ts — layerLive
• apps/server/src/factory/runner/start.test.ts, messages.test.ts, pass.test.ts, index.test.ts — the ported and added tests

[rawphp]

Factory gate: passed (attempt 1, run by the factory in a fresh checkout of the pull request's head 9f46619 merged with the base branch tip a8a24e2)

Command	Exit	Time
factory/scripts/check.sh	0	35.2 s

[rawphp]

Factory gate: passed again (attempt 2, run by the factory in a fresh checkout of the pull request's head 8265cc9 merged with the base branch tip a8a24e2)

Command	Exit	Time
factory/scripts/check.sh	0	34.9 s