[AbirAbbas]

Merge together with #2619.

What this adds

factory.job_create can say more about the job it makes, and a job can be given reference material before its first run.

• factory.job_create takes optional open_issue (opens one GitHub issue with the title and text, through POST /v1/issues), group and milestone (opaque labels kept on the job and returned on its reads), budget (one of the standard steps, the job's cap from creation), key (sent as Idempotency-Key, and only to a Factory whose GET /v1/features lists keyed_create; there a resend with the same key within 24 hours does not make a second job or issue) and split_from (the job this one was split from: a job of the same Factory the caller can see; the new job's reads return it and its activity records split from #N; the parent is unchanged).
• factory.job_context_set {factory, job, expect, context} replaces a job's context attachments while it has no run: up to 20 {title, markdown, source?} items, 100,000 characters in all, outside the description limit. The plan step that runs reads them (the first conversation step when there is no plan step). Job reads list them by title and source only; they never go to GitHub.
• Announced as: capabilities create_issue, create_group, create_budget, create_split_from and job_context. create_key is true only in an answer to factory.capabilities {factory} (a new optional parameter) for a Factory that lists keyed_create, and false without factory. Hello feature factory.job_context. A Factory older than a field or route answers conflict with detail.reason: "factory_too_old" and nothing changes.
• A create key goes only to a Factory that says keyed_create. A Factory older than Factory: a keyed create that wrote nothing runs again, announced as keyed_create; a rate-limited poll says so #2619 keeps every keyed answer for 24 hours, a refusal or a 5xx included, so a fixed per-draft key would replay a transient failure or a fixed refusal for a day. The engine asks GET /v1/features on every create that carries a key. To a Factory without the word that create answers conflict with detail.reason: "factory_too_old", and no create is sent. Creates without a key are unchanged. Two limits remain: a resend under a new bearer or session cookie is not matched, and a Factory that stops after committing a create but before saving its answer runs the resend again.
• The chat manual's Factory page describes making a job with an issue, labels, a budget, a retry key and a split parent.

Who calls it

The desktop app's Work place (codeaf-desk crates/core/src/engine/factory_actions.rs, factory_create_extras.rs, factory_job_context.rs) already sends these behind the capability flags: a workstream's Launch sends group, milestone, budget and context, and its failed-job card splits a job. Its retry key goes out only when create_key is true. The desk asks factory.capabilities without naming a Factory, so it gets create_key: false and sends no key until it passes factory. No engine on dev announces them today.

Where it comes from

This carries #2415 and #2429, which merged only into workstreams/main. That branch's integration PR (#2306) is closed and will not merge. Adapted to dev as it is now:

• Go-aheads are untouched. dev has its own group policies and waits (factory: follow go-aheads itself — group policies and waits-on #2524): an allowance names the jobs it covers by number. A job's group here is a label only and no policy reads it. Item, the wire Job and FactoryCapabilities keep dev's go-ahead fields; the original commit's WaitsOn/Blocked hunks were dropped.
• The retry key reuses the Factory's idempotency cache, and only a Factory that lists keyed_create gets it (Factory: a keyed create that wrote nothing runs again, announced as keyed_create; a rate-limited poll says so #2619 adds the word and the rule). The engine keeps nothing new. This PR is safe without Factory: a keyed create that wrote nothing runs again, announced as keyed_create; a rate-limited poll says so #2619: no Factory lists the word, so no key is ever sent. internal/factory/api/keyed_create.go is the same file byte for byte on Factory: a keyed create that wrote nothing runs again, announced as keyed_create; a rate-limited poll says so #2619, so the two merge in either order.
• The split parent is read from its saved copy (Store.GetSaved, the follow-up 0190d57 on workstreams/main), so checking a split asks GitHub nothing about the parent's author and writes nothing to it. TestSplitFromValidationDoesNotHydrateParent is rewritten on dev's fixture and fails (1 lookup) with the hydrating read.
• Left out: a job outcome carrying the job's group. Job outcomes are Factory job outcomes: a durable cursor read and a pushed factory.event #2616; once both are in, that is a one-line follow-up.
• FactoryReasonTooOld lives in internal/appwire/factory_too_old.go. factory.repo_issues, and a GitHub rate limit on a repository check answers retry #2618 adds the same file byte for byte, so the two merge in either order.

Tests

CI on this head (f0996a4): check, light gate, touched codeaf, touched rest, touched session, touched tui3, touched packages and windows native tests pass.

Locally (macOS), on this head (f0996a4):

• In cmd/codeaf, by name with -p 2: TestAppFactoryCreateCapabilities, TestAppFactoryCreateKeyGoesOnlyToAFactoryThatSaysSo, TestAppFactoryCreateKeyReplaysJobNumber, TestAppFactoryCreateRoutesBodyAndKey and their neighbours (every test that reads factory.capabilities, all create-extras, job-context and split_from tests, and the four job-action real-server tests): 40 of 40 pass. On the code before this round, the first three fail: create_key was true with no Factory named, and a key reached a Factory that does not list keyed_create and made a job.
• go test -count=1 -p 2 ./internal/appwire/ ./internal/factory/api/ ./internal/factory/serve/: all ok.
• make test-packed-manual manual-gates: exit 0. make changelog-check: 795 entries, all well formed. make test-quick: exit 0.
• Merged with Factory: a keyed create that wrote nothing runs again, announced as keyed_create; a rate-limited poll says so #2619 (c937532) on dev 6616e85, in a throwaway worktree: go build ./... ok; internal/factory/serve, api, run, store and internal/appwire ok; 41 named cmd/codeaf tests pass. One of them was a throwaway end-to-end test: the real merged Factory gets create_key and the key, a pre-write 501 under the key runs again, and then the same key replays one job. The same server answering features as an older Factory does gets create_key: false, a keyed create answers factory_too_old, and the older Factory never sees the key. The same test on this branch alone fails as intended, because no Factory lists the word. Manual gates, make changelog-check (803 entries) and make test-quick exit 0.

Locally (macOS), on the earlier head d773433, make pr-ready did not pass as one command. The PR was marked ready on the strength of CI and the comparison with dev below:

• The light gate passed (build, vet, formatting, packed manual, change entries, manual gates, laws).
• The touched packages other than cmd/codeaf passed fresh:

  ok  	github.com/Agent-Field/codeaf/internal/appwire	3.397s
  ok  	github.com/Agent-Field/codeaf/internal/factory	8.924s
  ok  	github.com/Agent-Field/codeaf/internal/factory/api	0.187s
  ok  	github.com/Agent-Field/codeaf/internal/factory/pipeline	2.786s
  ok  	github.com/Agent-Field/codeaf/internal/factory/record	1.344s
  ok  	github.com/Agent-Field/codeaf/internal/factory/run	178.812s
  ok  	github.com/Agent-Field/codeaf/internal/factory/serve	115.930s
  ok  	github.com/Agent-Field/codeaf/internal/factory/store	8.528s
  

• The cmd/codeaf leg was refused inside pr-ready by the one-heavy-suite lock (other sessions were running suites on the machine), so it was run by itself once the lock was free (make test PKGS=./cmd/codeaf TEST_FLAGS='-count=1 -p 2' SHARDS=8). 12 tests failed. None is attributable to this change:
  • 9 fail the same way alone on a clean origin/dev (ffeeb78) on the same Mac: TestAppFactoryPlanFilesAnswer, TestFactoryCommandStepRetryAfterOutOfAttempts, TestFactoryMeasuredOnlyPublication, TestFactoryRetryActionsDoNotReportStopped, TestFactoryStepRetryWaitsForPreviousLeaseCleanup, TestFactoryWriteUsesJobBaseAcrossAttempts, TestMemoryPauseResumeAfterTrailingProgress, TestMemoryPauseRetainsPendingForResume, TestMemoryPausedJobLifecycle (for example write is not green: exit 127: the Factory's command steps do not find their shell on this Mac).
  • TestHostedTakeBackReachesAcquireWithoutSharedUploadsOrReleaseDelay and TestPoolJudgeHookAppendsOutboxRowsOnlyWhenTheModeSends passed when run again.
  • TestProcessCloseJoinsTheUsageWriter passes alone (3 of 3) and fails after those two in one process (live usage writers = 2, want 0); it fails the same way in that order on clean origin/dev.

The change's own tests pass locally: the TestAppFactoryCreate* and TestAppFactoryJobContext* tests in cmd/codeaf (capabilities, routes, retry key, older-Factory refusals, split parent), the create-extras, job-context and split tests in internal/appwire, internal/factory/serve, internal/factory/run, internal/factory/api, internal/factory/pipeline and internal/factory/store, and make test-packed-manual manual-gates for the manual page.

The engine answers create_issue, create_group, create_budget, create_split_from and job_context as true from factory.capabilities {} and announces factory.job_context in hello. create_key is true only for a named Factory that lists keyed_create (TestAppFactoryCreateCapabilities; on dev + #2617 + #2619, a real Factory gets the key and an older one does not).

Changes after review

Round 1.

• A 404 from the current Factory's POST /v1/issues was always reported as factory_too_old, including its JSON 404 repository not found for a repository the person cannot see. Now only a 405, or a 404 whose body is not JSON or says factory endpoint not found, means a Factory too old. Any other 404 stays not_found with the Factory's words. The check is one helper, missingRouteBody, shared with the job-context route (c5dd897).
• An explicit $5 starting budget could be lowered after the clone. The settle rule (settledCap) took any $5 cap for the default a start used before the rules were read, and lowered it to a smaller rules default. A create's budget is now marked as chosen (Item.CapChosen, carried to the runner in the job desk section and kept by Run as new), and the settle skips a chosen cap. Old jobs and creates without a budget behave as on dev (520e293).
• The docs said context markdown must be non-empty. They now say it must contain more than whitespace, which is what the code refuses, and the Factory's refusal test has a blank-markdown row (61242ad).
• The retry-key docs claimed a replay rule that Factory: a keyed create that wrote nothing runs again, announced as keyed_create; a rate-limited poll says so #2619 changes. They were cut back to what holds with or without Factory: a keyed create that wrote nothing runs again, announced as keyed_create; a rate-limited poll says so #2619, and the change entry said the two must merge together (61242ad; 3879b8c brought the manual section back under its size).

Pass 2.

• Review found that a fixed per-draft key is unsafe against a Factory older than Factory: a keyed create that wrote nothing runs again, announced as keyed_create; a rate-limited poll says so #2619. That Factory keeps every keyed answer for 24 hours, so a transient failure or a fixed refusal came back for a day, even the factory_too_old refusal after the Factory was updated. The engine now sends a key only to a Factory that announces Factory: a keyed create that wrote nothing runs again, announced as keyed_create; a rate-limited poll says so #2619's rule (f6e2659):
  • factory.capabilities takes an optional {factory} (appwire.FactoryCapabilitiesParams). The dispatcher owns create_key: it is true only when a Factory is named, the engine implements the new optional appwire.FactoryCreateKeys, and that Factory's GET /v1/features lists keyed_create. With no Factory named, or a Factory that does not list it or cannot be asked, it is false. appBackend no longer claims it on its own, and the Factory interface and its callers are unchanged.
  • createJob reads GET /v1/features again on every create that carries a key. Without the word it answers conflict with detail.reason: "factory_too_old" and sends no create. A 404 on /v1/features means a Factory older than the route, so the same refusal. Any other failure of that read returns the read's own error and sends nothing. An unknown Factory stays not_found. A create without a key is unchanged and makes no extra read.
  • It refuses rather than dropping the key, because a caller that sent a key expects a resend after an uncertain answer to be safe. Dropping it could make a second job.
  • internal/factory/api/keyed_create.go, which defines the word, is the same file byte for byte on Factory: a keyed create that wrote nothing runs again, announced as keyed_create; a rate-limited poll says so #2619.
• The docs now state the two replay limits: a resend under a new bearer or session cookie is not matched, and a Factory that stops between committing a create and saving its answer runs the resend again (d59d286).
• The manual again names a 404 whose body is not JSON as a Factory too old; round 1's size trim had dropped it (f0996a4).
• A desk follow-up, outside this PR: the desk on main calls factory.capabilities without a Factory, so it now gets create_key: false and sends no key. Its keyed retry comes back once it passes factory for the workstream's Factory.

🤖 Generated with Claude Code