[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10,"_11":12},"actionData","errors","root",{"_228":-5,"_231":232,"_233":234},"routes/shell",{"_40":41,"_227":-5,"_228":-5,"_229":230},"routes/repo",{"_33":-7,"_34":35,"_36":37,"_38":39,"_40":41,"_42":31,"_43":31,"_44":31,"_45":31,"_46":31,"_47":31,"_48":49,"_50":49,"_51":31,"_52":-7,"_53":-7,"_54":55,"_56":57,"_58":59,"_60":-5,"_61":62,"_63":64,"_65":66,"_67":68},"routes/repo.blob",{"_13":14,"_15":16,"_17":18,"_19":20,"_21":14,"_22":23,"_24":-5,"_25":26,"_27":28,"_28":29,"_30":31,"_32":14},"ref","8564aeca07f7e28a8151960bd2f668a2790abbf7","path","docs/background-jobs.md","oid","495c6438cc7e89b017d4e315fb1ff0c201505d2e","size",34955,"commit","mounts",[],"source","plain",{"_13":14,"_15":16},"kind","text","# Background jobs and workers\n\nChopin's background system runs durable, versioned work outside the shared\nPlanner conversation. A job may execute ordinary code or open one or more\nisolated Copilot worker sessions. The code calls the durable unit a **background\njob**; this document uses **worker** for the disposable execution session. A\nworker is not a child Planner turn, coding agent, or runtime plugin.\n\n> [!IMPORTANT]\n> The registry is a closed, code-owned allowlist. Persisted rows name a\n> registered job type and version; they never contain executable code. Adding a\n> job requires a source change and deployment.\n\nThis guide covers the generic job framework, how to register a new definition,\nand the worker boundaries used by generated document descriptions and Research Workspaces.\nSee [Hosted agent](hosted-agent.md) for the Planner conversation and\n[Storage](storage.md) for the broader durable model.\n\n## Vocabulary\n\n| Term | Meaning |\n| ------------------------------- | -------------------------------------------------------------------------------------------------- |\n| Definition | The code-owned `JobDefinition` for one `type@version`. |\n| Job | One durable request, including normalized input and lifecycle state. |\n| Target | The semantic resource a job updates, such as one document or Research Workspace turn. |\n| Target generation | The newest request for a target. A newer generation supersedes older active work. |\n| Attempt | One job claim. Credential or capacity failure may prevent its executor from starting. |\n| Failure | An attempt that consumes retry budget. `failures`, not `attempts`, is compared with `maxAttempts`. |\n| Claim generation | A fencing counter that prevents an expired or cancelled worker from publishing late output. |\n| Artifact | The immutable, validated JSON result written only when a job completes. |\n| Worker | A disposable execution context, optionally backed by an isolated Copilot SDK session. |\n| Background Work | The generic browser view of current jobs, progress, and supported result previews. |\n| Background-job channel revision | The invalidation counter for job mutations in one channel, separate from each job's revision. |\n\nKeep these counters separate from the Yjs epoch, document sequence, plan\nrevision, storage revision, Research Workspace revision, and implementation\ngraph counters.\n\n## Architecture\n\n```mermaid\nflowchart LR\n\tE[Scheduler, user route, or domain service] --> S[JobService]\n\tS -->|validate, normalize, fingerprint| P[(PostgreSQL)]\n\tP -->|fenced claim| R[JobRunner]\n\tR --> C[Credential resolver]\n\tC --> X[Registered executor]\n\tX -->|optional disposable session| A[Copilot worker]\n\tX -->|progress| P\n\tX -->|candidate artifact| S\n\tS -->|validate and settle| P\n\tP --> I[job:changed invalidation]\n\tP --> D[Optional domain reconciliation]\n```\n\nThe main boundaries are:\n\n- `JobRegistry` stores every supported definition version and selects the\n highest version for new work.\n- `JobService` owns origin checks, canonical JSON, byte limits, fingerprints,\n enqueueing, control mutations, artifact validation, and publication hooks.\n- `BackgroundJobStore` owns durable state transitions, target generations,\n claims, progress, and artifacts.\n- `JobRunner` polls and wakes for work, resolves credentials, enforces\n concurrency, heartbeats claims, executes definitions, and handles retries and\n shutdown.\n- A definition's executor owns the actual work and any worker-specific\n capability boundary.\n\nProduct code should enqueue through `JobService`, not call\n`storage.jobs.enqueue()` directly. The raw storage port enforces persistence\ninvariants but does not know registry versions, origins, codecs, or byte limits.\n\n## Registration checklist\n\n1. Choose a stable lowercase type and start at version 1.\n2. Define strict, deterministic input and artifact codecs.\n3. Select only the origins an actual caller needs; enforce authorization at the\n route, socket, scheduler, or tool boundary.\n4. Select `active-planner` or `none` deliberately. For a user-triggered\n `active-planner` job, establish or validate ownership before enqueueing.\n5. Set timeout, failure budget, aggregate AI-credit metadata, and byte limits.\n6. Declare fixed progress stages without private or model-generated text.\n7. Implement execution with cancellation, deadlines, and bounded cleanup.\n8. For model work, use fresh audited workers and structured result tools.\n9. Add a publication hook only when completion needs a freshness gate.\n10. Register every supported version in `apps/server/src/main.ts`.\n11. Add an explicit scheduler, route, domain service, or Planner tool that\n enqueues through the matching `JobService.enqueue*()` method.\n12. Choose stable target and idempotency keys; do not pre-prefix the target.\n13. Add idempotent domain reconciliation if completion creates related state.\n14. Add explicit browser or Planner projection only when required.\n15. For new domain persistence, add and register a migration, update both\n adapters, and extend the shared storage contract.\n16. Test codecs, origins, authorization, retries, cancellation, credentials,\n publication, storage contracts, and every exposed UI path.\n\n## Definition contract\n\nA registered definition has this shape:\n\n```ts\ntype JobDefinition = {\n\ttype: string;\n\tversion: number;\n\tlabel: string;\n\tdescription: string;\n\torigins: readonly (\"scheduler\" | \"planner\" | \"user\")[];\n\tcredential: \"active-planner\" | \"none\";\n\tlimits: {\n\t\ttimeoutMs: number;\n\t\tmaxAttempts: number;\n\t\tmaxAiCredits: number;\n\t\tmaxInputBytes: number;\n\t\tmaxArtifactBytes: number;\n\t};\n\tprogress?: Readonly>;\n\tinput: { parse(value: JsonValue): Input };\n\tartifact: { parse(value: JsonValue): Artifact };\n\texecute(execution: JobExecution): Promise;\n\tpublish?(publication: JobPublication): Promise;\n};\n```\n\n`JobRegistry` validates definitions when the process starts:\n\n- types and progress stages use lowercase hyphenated identifiers;\n- versions and limits are positive safe integers;\n- labels and descriptions are nonblank;\n- at least one origin is declared, with distinct members of `scheduler`,\n `planner`, and `user`;\n- credential mode is `active-planner` or `none`;\n- progress, when present, has 1 through 32 code-owned labels, each at most 160\n characters;\n- only one definition may claim a particular `type@version`.\n\n`label` and `description` are catalog metadata. The current generic browser UI\ndoes not render them automatically.\n\n### Strict codecs\n\nInput and artifact codecs are security and compatibility boundaries. They\nshould:\n\n- accept exact fields and reject unknown ones;\n- normalize deterministically;\n- enforce semantic, collection, and string bounds;\n- return plain JSON only;\n- reject `undefined`, dates, class instances, accessors, sparse arrays,\n non-finite numbers, and cyclic values;\n- validate provenance and relationships rather than trusting model output.\n\n`JobService` canonicalizes JSON before and after the input codec. Object keys are\nsorted, nesting is bounded, UTF-8 bytes are measured, and the normalized form is\nused in the idempotency fingerprint. Settlement applies the same process to the\nartifact codec.\n\nChanging a persisted contract normally requires a new definition version. Keep\nold versions registered while durable pending, paused, or running rows can still\nreference them. New enqueue requests use the highest registered version; the\nrunner and settlement always resolve the exact persisted version.\n\n## Minimal definition\n\nThe following skeleton shows a non-model job. Real codecs should usually be more\nspecific than these examples.\n\n```ts\nimport { JobExecutionError } from \"./registry\";\n\nimport type { JsonValue } from \"../storage/model\";\nimport type { JobDefinition } from \"./registry\";\n\ntype ExampleInput = {\n\tresourceId: string;\n};\n\ntype ExampleArtifact = {\n\tresourceId: string;\n\tresult: string;\n};\n\nasync function analyze(\n\tresourceId: string,\n\tsignal: AbortSignal,\n\tdeadline: Date,\n): Promise {\n\tif (signal.aborted || Date.now() >= deadline.getTime()) {\n\t\tthrow new Error(\"analysis stopped\");\n\t}\n\treturn `Analyzed ${resourceId}`;\n}\n\nfunction record(value: JsonValue): Record {\n\tif (!value || typeof value !== \"object\" || Array.isArray(value)) {\n\t\tthrow new Error(\"expected object\");\n\t}\n\treturn value;\n}\n\nfunction input(value: JsonValue): ExampleInput {\n\tlet item = record(value);\n\tlet resourceId = typeof item.resourceId === \"string\" ? item.resourceId.trim() : \"\";\n\tif (Object.keys(item).length !== 1 || !resourceId || resourceId.length > 128) {\n\t\tthrow new Error(\"invalid example input\");\n\t}\n\treturn { resourceId };\n}\n\nfunction artifact(value: JsonValue): ExampleArtifact {\n\tlet item = record(value);\n\tif (\n\t\tObject.keys(item).length !== 2\n\t\t|| typeof item.resourceId !== \"string\"\n\t\t|| typeof item.result !== \"string\"\n\t\t|| item.result.length > 4_000\n\t) throw new Error(\"invalid example artifact\");\n\treturn { resourceId: item.resourceId, result: item.result };\n}\n\nexport function exampleDefinition(): JobDefinition {\n\treturn {\n\t\ttype: \"example-analysis\",\n\t\tversion: 1,\n\t\tlabel: \"Example analysis\",\n\t\tdescription: \"Analyzes one example resource.\",\n\t\torigins: [\"user\"],\n\t\tcredential: \"none\",\n\t\tprogress: { analyze: \"Analyzing resource\" },\n\t\tlimits: {\n\t\t\ttimeoutMs: 60_000,\n\t\t\tmaxAttempts: 2,\n\t\t\tmaxAiCredits: 1,\n\t\t\tmaxInputBytes: 8 * 1024,\n\t\t\tmaxArtifactBytes: 16 * 1024,\n\t\t},\n\t\tinput: { parse: input },\n\t\tartifact: { parse: artifact },\n\t\tasync execute(execution) {\n\t\t\tawait execution.progress(\"analyze\", \"started\");\n\t\t\tif (execution.signal.aborted) {\n\t\t\t\tthrow new JobExecutionError(\"analysis-cancelled\");\n\t\t\t}\n\t\t\tlet result = await analyze(\n\t\t\t\texecution.input.resourceId,\n\t\t\t\texecution.signal,\n\t\t\t\texecution.deadline,\n\t\t\t);\n\t\t\tawait execution.progress(\"analyze\", \"completed\");\n\t\t\treturn artifact({ resourceId: execution.input.resourceId, result });\n\t\t},\n\t};\n}\n```\n\nEven a credential-free definition currently needs positive `maxAiCredits`.\nThat field is catalog metadata, not proof that AI is used.\n\n## Register a definition\n\nDefinitions are assembled explicitly in `apps/server/src/main.ts`:\n\n```ts\nlet definitions: JobDefinition[] = [];\nif (config.backgroundJobs) {\n\tdefinitions.push(exampleDefinition());\n}\nlet jobRegistry = new JobRegistry(definitions);\n```\n\nThere is no directory scan or plugin discovery. Register every version that may\nstill have durable work:\n\n```ts\ndefinitions.push(exampleDefinitionV1(), exampleDefinitionV2());\n```\n\nRegistration alone does not schedule work or create an API. Add an explicit\nenqueue path using the intended origin method:\n\n```ts\nlet result = await jobs.enqueueUser({\n\tchannelId,\n\ttype: \"example-analysis\",\n\ttargetKey: resourceId,\n\tidempotencyKey: `example-analysis:${requestId}`,\n\tinput: { resourceId },\n});\n```\n\nChoose the origin method deliberately:\n\n| Method | Intended caller |\n| -------------------- | ----------------------------------------------- |\n| `enqueueScheduler()` | A code-owned scheduler or coordinator. |\n| `enqueuePlanner()` | A Planner tool or Planner-origin domain action. |\n| `enqueueUser()` | An explicit authenticated user action. |\n\nCallers do not supply an origin field. The service stamps it and checks that the\ndefinition permits it.\n\nOrigins record how work entered the system; they are not authentication or\nauthorization. A browser route must still authenticate the session, enforce\nOrigin, admission, repository node identity, and role. Planner tools and\nschedulers must enforce their own trusted ingress before calling `JobService`.\n\nThe caller supplies the semantic target without the job type prefix.\n`JobService` changes `resource-id` into\n`example-analysis:resource-id`. Supplying an already-prefixed target would\nproduce `example-analysis:example-analysis:resource-id`.\n\n### Idempotency and supersession\n\nAn idempotency key is unique within a channel. Reusing it with the same\nfingerprint returns the original job with `repeated: true`; reusing it with\ndifferent normalized input, origin, target, version, or availability conflicts.\n\nA new idempotency key for the same target increments the target generation and\nsupersedes older pending, paused, or running generations. Older terminal rows\nremain durable, but consumers must reject artifacts whose target generation is\nno longer current.\n\nUse request identity for idempotency and resource identity for the target. Do\nnot generate both from the current time.\n\n## Durable lifecycle\n\n```text\npending -> running\npending/running -> paused\npaused -> pending\nrunning -> pending retry or process recovery\nrunning -> completed\nrunning -> failed\npending/paused/running -> cancelled\npending/paused/running -> superseded\n```\n\nThe lifecycle is:\n\n1. `JobService` resolves the current definition, validates origin and input,\n computes the fingerprint, and enqueues under the writer fence.\n2. Storage advances the target generation, supersedes older active work, and\n inserts a pending row before `job:changed` is published.\n3. `JobRunner` polls globally and wakes immediately for local pending changes.\n4. Storage claims current pending work with `FOR UPDATE ... SKIP LOCKED`, or\n reclaims an expired running claim.\n5. The runner resolves the exact persisted definition version and parses the\n persisted input again.\n6. The runner resolves any required credential, stores only token-free binding\n metadata, and applies global and per-owner concurrency.\n7. The executor receives cloned input, credential, abort signal, deadline, and\n progress callback.\n8. `JobService` validates the candidate artifact and runs any publication hook.\n9. Fenced storage atomically marks the job completed and inserts its immutable\n artifact.\n10. Generic and domain-specific invalidations happen only after persistence.\n\nThe default runner uses global concurrency 2, per-owner concurrency 1, a\n30-second claim TTL, a 10-second heartbeat, one-second polling, exponential\nretry up to five minutes, and a 10-second shutdown grace period.\n\n### Claims and late output\n\nEvery claimed mutation must match the channel, job ID, process claim owner,\nclaim generation, unexpired claim, and current target generation. Cancellation,\nsupersession, owner revocation, timeout, or shutdown clears or invalidates that\nclaim. A worker may continue briefly if it ignores cancellation, but its late\nprogress and artifact cannot commit.\n\n`claim_owner` identifies the runner process, not the Planner owner or an\nauthorization principal.\n\n### Attempts and retries\n\n`attempts` increments on every claim. `failures` increments only when a retry\nconsumes failure budget. Despite its name, `JobLimits.maxAttempts` is currently\ncompared with `failures`.\n\nCredential rotation, owner capacity, shutdown, and similar recovery paths may\nrequeue without increasing `failures`. A `JobExecutionError` supplies a safe,\ncode-owned durable reason; an unclassified executor failure becomes\n`attempt-error`.\n\nDefinitions must honor both `execution.signal` and `execution.deadline`, and\nmust clean up disposable resources in `finally`. Fencing protects persistence;\nit does not stop leaked external work.\n\n### Progress and diagnostics\n\nProgress stages must be declared by the definition. The executor can append\n`started` and `completed`. The runner makes a best-effort `interrupted` append\nwhile it still owns the claim; cancellation, supersession, or claim loss may\nleave no interruption entry. Storage retains at most 32 entries.\n\nStage IDs, labels, and reason codes are durable and browser-visible. Structured\ndiagnostics are bounded but log-only. Neither category may contain:\n\n- prompts or model prose;\n- query text or private document content;\n- source URLs or provider payloads;\n- credentials, paths, or raw errors.\n\nUse `JobExecutionError` for a bounded durable machine reason and optional\noperator diagnostic. It accepts at most 16 boolean, nonnegative integer, or\ntoken-like string diagnostic fields. Unknown browser reasons are deliberately\nrendered as a generic interruption.\n\n## Publication hooks\n\nA definition may delay completion with `publish()`:\n\n```ts\nasync publish({ job, artifact, commit }) {\n\tif (!await stillCurrent(job, artifact)) {\n\t\tthrow new Error(\"target changed before publication\");\n\t}\n\tawait commit();\n}\n```\n\nThe hook runs after artifact validation but before settlement. It must call and\nnormally await `commit()` exactly once while the hook is active. A hook that\ndoes not commit leaves the attempt uncompleted; a late or second commit is\nrejected. If the hook commits and then throws, the durable completion remains\nauthoritative and the service logs the hook error.\n\nUse a publication hook only when completion needs an external freshness or\nserialization guard. `document-summary@1` uses one to hold the document mutation\ngate and recheck revision and source hash. Ordinary jobs settle directly.\n\nThe generic service publication callback sends only a background-job channel\nrevision invalidation. A separate domain service may observe a completed job and\npersist its own projection. That reconciliation must be idempotent and\nrecoverable on a later read because observer delivery is not a durable queue.\n\n## Credentials and ownership\n\n`credential: \"active-planner\"` means the job uses the channel's existing\nPlanner owner and Copilot entitlement. The runner resolves ownership through\n`ActiveOwnerBindings`; it never claims ownership itself. An explicit product\naction may establish ownership before enqueueing. Without an available owner,\nthe job pauses as `owner-unavailable`.\n\nResolution and later revalidation check the process-local session, credential\nrevision, ownership generation, instance admission, repository node identity,\nGitHub App installation, repository write role, and expiry. Definitions must\nnever copy the GitHub token into input, artifacts, progress, diagnostics, or\nPostgreSQL. A durable claim binding contains only the owner session ID, owner\ngeneration, credential revision, and repository ID.\n\n`credential: \"none\"` skips owner resolution. The current server still disables\nthe entire runner when `AGENT=off`, so a credential-free definition does not run\nunder that flag without a deliberate change to the main runner gate.\n\n## Model-backed workers\n\nDo not reuse the Planner conversation session. Every worker stage opens a fresh,\ndisposable SDK session. Most stages submit one bounded structured result;\ngenerated document descriptions reuse one disposable session for multiple\nbounded chunk and reduction turns.\n\n### Private worker\n\nUse `Agent.openWorker()` for private document or repository-derived material.\nThe effective capability set must contain only the definition's terminal result\ntool. Private workers receive no MCP server, web search, URL fetch, repository\ntool, shell, filesystem, host Git, skill, or plugin.\n\n### Public research worker\n\nUse `Agent.openPublicResearchWorker()` only for an explicitly disclosed public\nquery. Its fail-closed capability audit requires exactly:\n\n```text\ncustom:submit_research_result\ngithub-mcp-server/web_search\n```\n\nNever give one session both private context and public web capability. The\npublic evidence worker receives only the confirmed query; a later private\nanswer worker receives normalized evidence and private context.\n\nAccepted public sources must be canonical public HTTPS URLs observed in\nsuccessful web-search citation or typed-resource metadata. Bare URLs in model\nprose do not establish provenance. Chopin never follows, resolves, or fetches a\nsource URL, and generated reports may cite only URLs retained in normalized\nevidence. This validates provenance, not factual accuracy or page safety.\n\n### Executor-owned limits\n\n`JobLimits.maxAiCredits` is not centrally enforced by `JobRunner`. It describes\nthe maximum aggregate credits for one job attempt. A model-backed executor must\nset per-session limits whose possible total does not exceed it; for example, a\n60-credit two-stage job can allocate 30 credits to each worker. The current\nworker helper requires at least 30 credits per session. Keep definition metadata\nand actual worker construction synchronized.\n\nAlways recheck `credential.authorize`, observe credential and job abort signals,\nand discard the SDK session in `finally`.\n\n## Current definitions\n\n| Definition | Production trigger | Persisted input | Worker boundary |\n| --------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |\n| `document-summary@1` | Open, edit, restore, or MCP persistence | Revision, source hash, generator version, and `output:\"description\"`; not the source | Private worker; source loaded at execution and publication rechecks current revision/hash |\n| `research-evidence@1` | Human confirmation or explicit Search more | Workspace, turn, exact public query | Public worker with only result tool and audited `web_search` |\n| `research-answer@1` | Completed evidence or private follow-up | Document source snapshot, evidence, bounded thread, and optional original report | One or two private workers with only result tools |\n\n`document-summary@1` remains the only durable definition version; there is no\n`document-summary@2`. New V1 requests carry the output marker and use the\nidempotency key `description-v1::`. The distinct\nrequest identity means an unchanged document whose existing V1 artifact is a\nlegacy summary is eligible for lazy description generation.\n\nThe V1 codecs still read markerless legacy inputs and their `summary` artifacts.\nThose artifacts remain available through Background Work, but the catalogue\nprojector ignores them. A new marked artifact instead carries\n`output:\"description\"` and one physical line identifying the document's type,\npurpose, and subject, for example `PRD for ...`, `RFC about ...`, or `Plan for\n...`. The description retains the broad 4,000-codepoint and 16 KiB artifact\nsafety limits. A blank canonical source produces `Empty document` without a\nmodel call.\n\nScheduling is lazy rather than a database-wide backfill. Canonical edits\ndebounce new work; opening or restoring a document ensures work for its current\nsource; MCP creation and replay schedule after persistence. Execution requires\nthat channel's active Planner owner, so work pauses without an available owner.\nThere is no unattended scan that establishes owners or regenerates every stored\ndocument.\n\nAfter a marked job completes, an idempotent projector writes the description to\nchannel catalogue metadata with the source plan revision and hash, generator\nversion, source job ID, projection timestamp, and an independent description\nrevision. The previous description remains visible and searchable while newer\nwork is pending or failed. Projection does not advance collaboration revision or\nchannel `updatedAt`, so it does not change list recency.\n\nAllowed origins are broader than current callers: the document-summary\ndefinition permits scheduler and planner; research definitions permit user and\nplanner. Current production enqueue paths use scheduler for descriptions and\nuser for research execution.\n\nGenerated descriptions and legacy document-summary artifacts are not the\nreserved Planner transcript summary or an MCP creation `brief`. They are not\ninjected into a later Planner turn automatically. Descriptions are untrusted\nmodel output. The Planner may explicitly call `list_background_jobs` and\n`read_background_job`, and must treat the returned artifact as untrusted\nevidence.\n\n## Research Workspace orchestration\n\nResearch Workspaces illustrate a multi-job domain workflow:\n\n1. Sidebar or Planner creates a private, durable draft. This starts no\n background research.\n2. A writer reviews and confirms the exact public query. This or any later new\n model-backed turn may establish the channel's Planner owner when none exists.\n3. A `research-evidence` job sends only that query to public web search.\n4. Completed normalized evidence causes an idempotent `research-answer` enqueue.\n5. The answer job captures current canonical document context and runs without\n web capability.\n6. The immutable report remains in the answer artifact; a validated summary is\n projected into the append-only workspace thread.\n7. Ordinary follow-ups create only private answer jobs. Search more creates a\n new public evidence job followed by a private answer job.\n\nWorkspace and job mutations are separate fenced commits. Stable targets and\nidempotency keys let reconciliation find and link a job after interruption.\nCompletion observation also runs when a workspace is read, not only from the\nprocess-local job callback.\n\nHere, **private** means not disclosed to public web search. Drafts, confirmed\nqueries, messages, and selected domain projections and artifacts are readable by\nauthorized parent-channel readers. Normalized job input is persisted but omitted\nfrom browser and Planner job projections. Private worker material is still sent\nto the hosted Copilot inference service under the active owner's credential.\n\n## Archive and deletion\n\nArchiving a document suspends its description coordinator, cancels any pending\ndescription debounce, and prevents new description scheduling. It does not\nblanket-cancel background jobs already admitted for that channel. New Research\nWorkspace drafts, confirmations, follow-ups, and searches are blocked while\narchived, but already-started evidence and answer jobs may settle, and their\nidempotent workspace reconciliation may still persist.\n\nPermanent deletion has a stronger boundary. The runner first blocks new claims\nfor the channel while description scheduling remains suspended, aborts its active\nattempts, cancels every pending, paused, or running job, and waits a bounded\ngrace period. The server then closes the live plan before atomically deleting\nthe archived channel. Claim fencing rejects any late worker progress or\nartifact, and the channel delete cascades job targets, jobs, artifacts, Research\nWorkspaces, turns, and messages.\n\n## Storage and retention\n\nThe generic schema supports a new standalone job type without a migration:\n\n- `background_job_channels` stores the independent background-job channel\n revision;\n- `background_job_targets` stores current target generations;\n- `background_jobs` stores requests, state, claims, normalized input, progress,\n and sanitized failure reason;\n- `background_job_artifacts` stores one immutable completed result per job.\n\nA migration is needed only when the job adds domain-specific durable records or\nlinks, as Research Workspaces do. When changing `StorageAdapter`, update the\nmodel, port, memory adapter, PostgreSQL adapter, migration, migration registry in\n`apps/server/src/storage/postgres/migrations.ts`, migration tests, and shared\ncontract suite together. Never edit an applied migration; checksums make that a\nstartup error. See [Storage](storage.md#postgresql-schema) for the table map.\n\nJob summaries omit input, fingerprint, idempotency key, and claim binding. This\ndoes not make input ephemeral: normalized input is stored in PostgreSQL. For\nexample, document-description input omits document source, while research-answer\ninput deliberately persists the captured source snapshot. Store only material\nthe workflow needs and document its retention boundary.\n\nThere is no current pruning policy for jobs, artifacts, Research Workspaces, or\ntheir transcripts while their document remains stored. Cancellation prevents\npublication; it does not erase input or history. Full document deletion is the\nexception and removes all of that channel-owned state.\n\n## Browser and Planner integration\n\nGeneric status works through `job:list`, `job:get`, `job:cancel`, and\n`job:changed`. Repository readers may list and read. Cancellation requires\ncurrent write access and is currently restricted to active, user-origin\nresearch evidence and answer jobs.\n\nA newly registered type appears as generic Background work, but richer support\nis explicit. Add or update these when needed:\n\n- subject extraction in `apps/server/src/jobs/service.ts` and both job storage\n adapters;\n- safe browser serialization and cancellation rules in\n `apps/server/src/jobs/browser.ts`;\n- protocol declarations in `packages/protocol/job.d.ts`;\n- result decoding, labels, safe reasons, and controls in\n `packages/editor/src/background-work.tsx` and `packages/editor/src/jobs.ts`;\n- domain HTTP state and invalidations when the job belongs to a larger workflow.\n\nThe generic browser loads the newest 100 jobs and indicates truncation. It shows\nonly the newest generation per target. There are no browser pause or resume\ncontrols.\n\nThe Planner can list and read jobs, but has no generic enqueue, pause, resume,\ncancel, or artifact-trust capability. A domain-specific Planner tool must still\nrespect the job origin, authorization, disclosure, and persistence boundaries.\n\n## Configuration\n\nOnly the exact value `off` disables these flags:\n\n| `AGENT` | `BACKGROUND_JOBS` | `WEB_RESEARCH` | Result |\n| ------- | ----------------- | -------------- | ----------------------------------------------------------------------------------------------------------------- |\n| on | on | on | Document description, research evidence, and research answer definitions; runner and coordinator active |\n| on | on | off | Document description and private research answer definitions; no new public evidence |\n| off | on | forced off | Persisted Background Work and descriptions remain readable; the entire runner and description coordinator are off |\n| any | off | forced off | No definitions execute and generic Background Work is hidden |\n\nConfiguration is read at startup. Restoring a disabled capability requires a\nrestart. Existing durable rows and artifacts are not deleted by a flag.\n\n`AGENT=off` disables the entire runner, including `credential: \"none\"` jobs.\nGating a definition itself can leave durable rows paused as `unregistered-type`.\nPrefer keeping old definitions registered while gating new enqueue paths. If a\ndefinition must be removed conditionally, provide and test an explicit resume\npath; automatic owner recovery only revives compatible `active-planner` work.\n\nIf a new definition needs its own flag, update configuration parsing and tests,\n`.env.example`, Compose metadata and tests, self-hosting documentation, and the\nE2E server environment where relevant.\n\n## Common failure traps\n\n- Registering a definition without adding an enqueue path.\n- Removing an old version while durable work still references it.\n- Treating caller input as the job origin.\n- Treating a stamped origin as authentication or authorization.\n- Pre-prefixing the target key before calling `JobService`.\n- Reusing an idempotency key with changed semantic input.\n- Persisting tokens, raw provider events, prompts, or private prose in progress\n and diagnostics.\n- Assuming `maxAiCredits` is runner-enforced.\n- Assuming `maxAttempts` is compared with claim count rather than failures.\n- Ignoring the abort signal because claim fencing rejects late output.\n- Reusing a Planner session for background work.\n- Giving a private worker ambient MCP, URL, repository, shell, or filesystem\n capability.\n- Giving one worker both private context and public web search.\n- Calling an undeclared progress stage.\n- Calling a publication `commit()` twice, too late, or not at all.\n- Broadcasting or projecting state before its durable commit.\n- Assuming process-local completion callbacks are durable delivery.\n- Bypassing `JobService` and therefore bypassing codecs, origins, versions, and\n byte limits.\n- Assuming Playwright executes live Copilot work; E2E runs with `AGENT=off` and\n seeds validated job state.\n\n## Testing\n\nUse the narrowest tests that exercise the new behavior:\n\n```bash\n# Definition, service, runner, and domain tests\nbun test apps/server/src/jobs apps/server/src/research\n\n# Memory adapter and the rest of the unit/domain suite\nbun test\n\n# Real PostgreSQL transitions, fencing, and migrations\nbun run test:postgres\n\n# Type and static validation\nbun run types\nbun run ci\n\n# Browser integration when the job has a user-facing surface\nbun run e2e\n```\n\nDefinition tests should inject engines rather than call live Copilot. Cover\nstrict codecs, exact context separation, progress, citation or provenance rules,\nand artifact rejection. Runner tests should cover success, retries, timeout,\nowner loss, credential rotation, cancellation, heartbeat loss, late output, and\nshutdown. Storage behavior belongs in the shared adapter contract so memory and\nPostgreSQL run the same cases.\n\n## Main implementation points\n\n- Definition and registry contract: `apps/server/src/jobs/registry.ts`\n- Validation, enqueue, settlement, and publication: `apps/server/src/jobs/service.ts`\n- Claims, execution, retries, and shutdown: `apps/server/src/jobs/runner.ts`\n- Current definitions: `apps/server/src/jobs/document-summary.ts` and\n `apps/server/src/jobs/research-workspace.ts`\n- Document-description projection: `apps/server/src/jobs/document-description.ts`\n- Definition registration and runtime wiring: `apps/server/src/main.ts`\n- Active owner resolution: `apps/server/src/agent/active-owner.ts`\n- Private and public worker construction: `apps/server/src/agent/client.ts`\n- Durable job model and port: `apps/server/src/storage/model.ts` and\n `apps/server/src/storage/port.ts`\n- PostgreSQL job store: `apps/server/src/storage/postgres/jobs.ts`\n- Generic protocol and browser state: `packages/protocol/job.d.ts` and\n `packages/editor/src/jobs.ts`\n- Research orchestration: `apps/server/src/research/service.ts`\n","editable",false,"branch","documentNavigation","repo","githubnext/chopin","repoId","7d1a8ac3-35b0-4dea-85d4-06a980f3bada","ownerId","org:89615882","site","nexthub","private","admin","settings","maintainer","triage","starred","stars",0,"watchers","watching","pinned","notify","views",[183,184,185,186,187,188,189,190,191,192,193,194,195],"navigation",{"_54":55,"_139":140,"_141":142,"_143":144,"_145":146,"_147":148,"_149":150},"sources",[],"viewer","meta",{"_131":132,"_133":134,"_135":136,"_42":31,"_137":126,"_138":31,"_48":49,"_50":49},"branches",[73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130],"tags",[69,70,71,72],"cloneUrl","https://git.nexthub.sh/githubnext/chopin.git","color-controls-slice-1","color-controls-slice-2","color-controls-slice-3","color-controls-slice-4","Krzysztof-Cieslak-patch-1","Krzysztof-Cieslak-patch-2","Maggie/app-preview-toolkit","Maggie/ci-playwright-install-timeout","Maggie/collaborative-visual-decision","Maggie/design-audit","Maggie/generic-visual-decision-runtime","Maggie/impeccable-chopin-metadata","Maggie/jev-chat-product","Maggie/jev-composed-assessment","Maggie/native-document-layouts","Maggie/openui-composition-product","Maggie/openui-composition-trial","Maggie/planner-visual-authoring","Maggie/planner-visual-requests","Maggie/visual-selection-eval","artifacts/pr-419-live-preview-20261009","automation/pr-maintenance-state","automation/use-effect/callout-disabled-picker-8cf9e49ba5c09471","automation/use-effect/collaboration-options-ref-4e3a5a08a879a5ae","automation/use-effect/room-workspace-effective-access-a57d40866c71bed0","chore/bun-1.4.2","color-controls","color-controls-plan","comments","design-pr-assets","design/archived-decisions-badge","design/channel-route-remount","design/chat-decision-entry","design/conversation-analysis-markers","design/decision-evidence","design/settled-line-icon","dev/integration","diagram-step-controls","feat/liveapp-frontend-pilot","feat/local-experiments","feat/local-launcher-tracer","fix/autolink-mdx-crash","github-pills/2-pills","github-pills/3-hover-card","maggie/app-preview-toolkit","maggie/ci-playwright-install-timeout","maggie/collaborative-visual-decision","maggie/design-audit","maggie/generic-visual-decision-runtime","maggie/impeccable-chopin-metadata","maggie/jev-composed-assessment","maggie/native-document-layouts","maggie/openui-composition-product","maggie/openui-composition-trial","maggie/planner-visual-authoring","maggie/planner-visual-requests","maggie/visual-selection-eval","main","plain-text-fence-chrome","tokens/09-copy","wireframes/2-renderer","wireframes/3-planner","description","Let's compose rich plans together","owner","githubnext","section","","head","empty","pins",[165,166,167],"documents",{"_160":161,"_162":163},"code",{"_156":157,"_158":159},"automations",{"_153":154,"_155":-5},"delivery",{"_151":49,"_152":-5},"tag","04zvKQ8QOrDUF8TO1Ovz0Zy8_TT","releases","applications","workflows",3,"deployments","commits",1000,"changes",13,"counts",{"_164":163},"total",11,"issue",{"_168":158,"_170":181,"_15":158,"_172":182,"_52":174,"_175":31,"_176":174,"_177":159},{"_168":178,"_170":179,"_15":178,"_172":180,"_52":174,"_175":31,"_176":174,"_177":49},{"_168":169,"_170":171,"_15":169,"_172":173,"_52":174,"_175":31,"_176":174,"_177":163},"id","issues","name","Issues","filters",{},true,"saved","pinnable","count","tasks","Tasks",{},"Changes",{},{"_168":158,"_170":181,"_15":158,"_172":226,"_52":174,"_175":31,"_176":174},{"_168":178,"_170":179,"_15":178,"_172":225,"_52":174,"_175":31,"_176":174},{"_168":169,"_170":171,"_15":169,"_172":224,"_52":174,"_175":31,"_176":174},{"_168":221,"_170":222,"_15":221,"_172":223,"_52":31,"_175":31,"_176":174},{"_168":218,"_170":219,"_15":218,"_172":220,"_52":31,"_175":31,"_176":174},{"_168":153,"_170":216,"_15":145,"_172":217,"_52":31,"_175":31,"_176":174},{"_168":155,"_170":213,"_15":214,"_172":215,"_52":31,"_175":31,"_176":174},{"_168":151,"_170":211,"_15":151,"_172":212,"_52":31,"_175":31,"_176":174},{"_168":207,"_170":208,"_15":209,"_172":210,"_52":31,"_175":31,"_176":174},{"_168":141,"_170":205,"_15":141,"_172":206,"_52":31,"_175":31,"_176":31},{"_168":202,"_170":203,"_15":202,"_172":204,"_52":31,"_175":31,"_176":31},{"_168":199,"_170":200,"_15":199,"_172":201,"_52":31,"_175":31,"_176":31},{"_168":196,"_170":197,"_15":196,"_172":198,"_52":31,"_175":31,"_176":31},"decisions","Decisions",{},"changelog","Changelog",{},"roadmap","Roadmap",{},"Documents",{},"activity","Activity","insights",{},"Releases",{},"Deployments","automations/deployments",{},"Workflows",{},"discussions","Discussions",{},"goals","Goals",{},{},{},{},"groups","user","agents",[],"now",1794504836525,"sidebar","expanded"]