forgeos 0.1.0-alpha.67 → 0.1.0-alpha.68

package/.agents/skills/forge-agent-fabric/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: forge-agent-fabric
+description: Conduct or resume a Forge Agent Fabric coding task with persistent workflow steps, independent Codex review, and source-bound evidence when the user requests this workflow.
+---
+
+# Forge Agent Fabric
+
+Keep the user's conversation in Codex. Prepare protocol requests yourself; the user should
+not need to write JSON or operate a second interface. Respect the user's task scope and
+existing authorization. This skill does not authorize publication, deployments or external
+messages. Use subagents for implementation/review when authorized by the user or project.
+
+## Locate and connect
+
+Resolve the current project's Git root and read its AGENTS.md. Execute with that root
+as cwd, even when the runtime is installed elsewhere. Windows and WSL copies are distinct
+projects. This workflow does not require a Forge application or project dependency.
+
+Use the absolute path to this skill's `scripts/fabric.mjs` helper:
+`node <skill-directory>/scripts/fabric.mjs --project <target-git-root> <operation> --json`.
+It reads installer-generated runtime.json or FORGE_FABRIC_CLI and falls back to an installed
+Forge runtime on PATH. Never switch to the runtime's checkout to conduct work.
+
+Run `doctor --json` and `ensure-owner --json` through that helper. Register projects with
+`project-register --project-id <stable-id> --json`; inspect registrations with `project-list --json`.
+Registration is needed for multiproject MCP routing, not for ordinary cwd-bound CLI work.
+Optional project preparation, verification and limits live in `.forge/fabric.json`;
+inspect doctor and respect the current project's profile rather than inventing config fields.
+
+Forward `capabilities --json` through the helper to distinguish accompanied tasks,
+managed SDK runs and the legacy Ollama pilot. When the user asks Fabric to execute a
+workflow or run Codex workers, select managed execution below. Choose accompanied mode
+when the task is to record work performed by the native session. Both modes need one
+owner; `ensure-owner` reuses or starts it without dispatching workers.
+Do not open the legacy PGlite database independently or kill an unrelated owner.
+
+Native MCP tools are `fabric_attached_*`, `fabric_workflow_*` and `fabric_run_*`. If unavailable, the CLI
+offers the same operations. State which transport you actually demonstrated.
+Do not register MCP or change global configuration as a side effect of using this skill.
+
+Read [managed request fields and examples](references/managed-workflows.md) before
+preparing run-start. The references travel with this skill and require no Forge checkout.
+For MCP, inspect tool schemas and select the registered target project explicitly through
+projectId when supported. A fixed-root MCP server is usable only when its root matches
+the target. Never assume a global MCP configuration follows the chat cwd.
+
+## Accompanied work
+
+1. Create an `attached-propose` with explicit acceptance criteria, relevant file scope and
+   checks. Mutations use a complete `--file` JSON request; reads use `--task-id`.
+2. Attach the actual session/agent identity, register an implementation assignment and
+   start its attempt. Use actual IDs from the host, not invented claims of verified identity.
+3. For a composed task, record `workflow-plan` and use `workflow-next` packets. Claim a
+   step before executing it, then report output digest and evidence. Before checking or
+   reviewing source, capture the current snapshot digest from `attached-status`. Successful
+   `workflow-result` and `workflow-reconcile` requests must include that actual observed
+   digest in the top-level `observedSnapshotDigest` field. Do not fetch a newer digest merely
+   to stamp an older result; if source changed, reconcile obsolete work as failed and
+   replan or execute a fresh attempt. The scheduler records
+   work; it does not invoke the host's subagent tools for you.
+4. Complete implementation and prepare a review with a distinct reviewer attempt.
+   Give that Codex subagent requirements, code and the returned exact snapshot/token.
+   Submit its report only for that version. Correct findings and obtain a new review
+   when files change. Do not mark findings resolved without corrective evidence.
+5. Run the checks relevant to the change and record their outcomes for the current
+   snapshot. Record criterion coverage with concrete artifacts or observed checks.
+6. Read `attached-status`. Address the structured unmet reasons before presenting the
+   task as ready. Agent-reported records retain that provenance; they are not authenticated
+   service executions, human acceptance or proof of production deployment.
+
+Reuse a requestId only for the exact same request, including expectedVersion. On a version
+conflict read current state and reconcile; use a new requestId for a new operation. Mutation
+responses are compact acknowledgements; status/context reads return current full state.
+
+## Resume and adapt
+
+Start with `attached-context` for the known taskId. Do not restart completed work from the
+conversation summary alone. After a host crash use `workflow-recover` for known interrupted
+attempts and reconcile their observed outcomes before dispatching them again. A missing
+result is uncertainty, not success or permission to repeat an effect.
+
+Use `workflow-replan` with the expected revision, reason and evidenceRefs. Preserve
+required obligations. Source changes make recorded results stale; the service blocks
+their reuse and replan invalidates affected steps and their dependents. The current
+release binds results conservatively to the task's whole file scope; choose a relevant
+scope and do not promise fine-grained invalidation by individual inputRefs.
+
+Keep hooks observational. Missing hook events do not prevent explicit session/tentative
+registration, but do prevent claiming that native hook integration has been demonstrated.
+The accompanied mode recovers work when Codex returns. Managed SDK runs now have a
+separate executor, but still require a live owner; neither mode installs automatic wakeup
+or guarantees execution after the App closes.
+
+## Managed execution
+
+Choose managed execution when the authorized task calls for owner-dispatched SDK or
+command workers. Keep the native chat as the interface and prepare requests yourself.
+Starting Codex workers can consume configured credits; local publication can change
+files. Use the user's existing scope and authorization, including any cost constraints.
+Do not treat the legacy proposal-only MCP contract as a limit on fabric_run_start.
+
+1. Read capabilities and the managed request example in the bundled reference. Prepare
+   run-start with requestId, goal, scope, workflow and one executor per node. Codex roles
+   are implementer/reviewer/investigator/decision; commands use explicit argv. Choose
+   relevant limits, deadlines and scope. inputDigest identifies the declared node contract;
+   the owner separately captures actual source inputs. Clones do not copy root node_modules;
+   automatic environment preparation installs locked dependencies or copies verified cache
+   into the clone, with scripts ignored by default. Optional environment accepts mode
+   auto/none, ignoreScripts, HTTPS registry without credentials/query/fragment, and timeoutMs
+   100..1800000. Use none for dependency-free steps. Do not assume ignored scripts executed.
+2. Start via `fabric run-start --file run.json --json` or fabric_run_start with
+   `{request: BODY}`. Read `run-status --run-id ID`; use run-wait with
+   `{runId,cursor,waitMs}` for bounded events, up to 30000 ms. MCP status uses `{runId}`.
+   Start and mutations return compact acks; status provides full public state and artifacts.
+3. For publication, use an implementer activity, a required distinct Codex reviewer
+   downstream of every writer, and a required command verification downstream of every
+   writer. Reviewer approval, command success and workflow completion are required.
+   publish false keeps isolated artifacts; publication applies local scoped files and
+   does not authorize commit, push or deployment. Do not claim that a model's report is
+   executor evidence: state is executor_observed, reports remain agent_reported, and
+   outputContract.requiredEvidenceKinds accepts only `executor-observed`.
+4. Steer queues instruction and pauses new dispatch; it does not message the active worker.
+   Pause allows active workers to finish. All controls use runId/requestId/expectedVersion.
+   Resume optionally adds expectedRevision/nodes/executors/reason/evidenceRefs for replan.
+   Read status after version conflicts and issue a new requestId for a changed body.
+5. After cancellation or owner restart, inspect the saved thread, workspace and effects.
+   Unknown attempts require run-reconcile with attemptId, resolution failed and reason;
+   never manufacture success or retry uncertain effects silently. A new isolated attempt
+   may use the saved SDK thread. Publication confirmation uses publication confirm only
+   when the owner can observe matching expected files. Resolve uncertainty before resume.
+   Publication retry is allowed only after observing the complete original baseline; it
+   clears the intent and pauses. Resume explicitly; preserve partial divergent writes.
+
+Distinguish implementation, command-fixture tests and actual SDK execution in the delivery
+report. Do not extend a past pilot's acceptance to a new environment or task without
+observed evidence. SDK workers are separate runs, not new chats in the sidebar. Keep the owner session
+visible in task context; do not promise App-closed execution or create a scheduler implicitly.

package/.agents/skills/forge-agent-fabric/references/managed-workflows.md

@@ -0,0 +1,95 @@
+# Managed Codex workflows
+
+Commands below are Fabric operation arguments forwarded through `scripts/fabric.mjs`.
+Use the current target Git root, not the directory containing the runtime. The owner
+captures source from that root and creates isolated Git clones. No root node_modules
+directory is shared with clones. A runtime installation is reusable across repositories.
+
+## Request shape
+
+Prepare `run-start --file <absolute-request.json> --json`; the request file must be inside
+the target Git root. Mutations use a complete JSON
+body; reads use `run-status --run-id ID --json`. The following command-only example
+needs an existing tracked `source.txt` and a working absolute Node executable. Generate
+a fresh requestId for each independent run. Replace example paths with observed paths.
+
+```json
+{
+  "requestId": "command-smoke-1",
+  "goal": "Observe a command in an isolated clone",
+  "scope": ["source.txt"],
+  "publish": false,
+  "environment": {"mode": "none"},
+  "workflow": {"workflowId": "command-smoke", "nodes": [{
+    "nodeId": "verify", "kind": "verification", "dependsOn": [],
+    "inputDigest": "sha256:2689367b205c16ce32ed4200942b8b8b1e262dfc70d9bc9fbc77c49699a4f1df",
+    "required": true,
+    "outputContract": {"requiredEvidenceKinds": ["executor-observed"]}
+  }]},
+  "executors": [{"nodeId": "verify", "type": "command",
+    "argv": ["/absolute/path/to/node", "-e", "process.stdout.write('ok')"],
+    "timeoutMs": 10000}]
+}
+```
+
+inputDigest describes the node contract, not the observed source. Calculate SHA-256
+for each actual declared contract. The example digest is SHA-256 of `ok` for this smoke.
+The owner separately captures source inputs. Evidence kind `executor-observed` means
+execution was observed; a model report's content remains `agent_reported`.
+
+For code use `implement -> review -> verify` with one executor per node:
+
+- implement: `kind: activity`, executor `{nodeId,type:"codex",role:"implementer",prompt,writeScope:[...]}`.
+- review: required activity, Codex `role:"reviewer"`, depending on every writer, prompt requesting independent review and explicit approval/findings.
+- verify: required verification, `type:"command"`, explicit `argv`, depending on every writer; use actual project tests/build checks.
+
+Scopes and writeScope are repository-relative. Ensure writeScope stays inside the run
+scope. Set timeoutMs and limits appropriate to the task. Use capabilities/doctor to check
+current constraints. Maximum supported concurrency is four; prefer a small useful fanout.
+Do not prescribe a test command without reading the project's scripts or AGENTS.md.
+
+Optional top-level run environment: mode `auto` (default) or `none`, ignoreScripts (default
+true), HTTPS registry without credentials/query/fragment, timeoutMs 100..1800000.
+Auto prepares locked dependencies or copies verified cache content into the clone.
+Ignored scripts have not executed; enable necessary preparation only within authorization.
+An optional `.forge/fabric.json` profile supplies maxConcurrency and environment defaults
+for run-start; explicit request fields win. verificationCommands are suggested argv arrays
+for the agent to select, never commands executed by doctor. Supported profile shape:
+`{schemaVersion:1,maxConcurrency:2,environment:{mode:"auto",ignoreScripts:true},verificationCommands:[["node","--test"]]}`.
+
+Publication is local file application, not npm publication. `publish:false` keeps clones
+and artifacts. `publish:true` (the default) requires approval from a distinct required
+Codex reviewer and successful required command verification downstream of all writers.
+Do not claim a model report proves a successful command, production deployment or human
+acceptance. Run with explicit publication intent matching the user's request.
+
+## Controls and recovery
+
+| Operation | Body |
+| --- | --- |
+| run-wait | `{runId,cursor?,waitMs}`; waitMs 0..30000 |
+| run-pause/run-resume/run-cancel | `{runId,requestId,expectedVersion}` |
+| run-steer | CAS fields plus `instruction`; pauses new dispatch |
+| run-reconcile | CAS fields plus `{attemptId,resolution:"failed",reason}` for uncertain attempts |
+
+Mutation acknowledgements are compact. Read run-status for full public state, source
+versions, attempts, artifacts and unmet requirements. Reuse requestId only for an exact
+body replay. After a version conflict read status and create a new requestId for a changed
+operation. Pause allows active workers to finish; steer does not inject messages into the
+active worker. Cancel requests interruption without rolling back external effects.
+
+Resume can replan with expectedRevision, nodes, executors, reason and evidenceRefs.
+Preserve required obligations, evidence requirements and limits. Source changes invalidate
+applicable results. Failed or uncertain attempts must not be represented as success.
+
+After an owner restart or interruption inspect saved workspace, SDK thread ID and effects.
+Unknown results require reconciliation before retry. New isolated attempts may reuse a
+saved SDK thread. Publication confirmation `{publication:"confirm"}` requires the owner
+to observe matching expected files. Retry `{publication:"retry"}` requires the complete
+original baseline, pauses the run, and needs explicit resume. Preserve divergent partial
+writes instead of overwriting them.
+
+MCP run mutations receive `{request: BODY}` plus projectId when routing is enabled;
+status receives `{runId}` plus projectId. Always inspect the available tool schema.
+CLI and MCP must target the same registered root. A configured MCP server being present
+does not prove its tool catalog is loaded or its owner is alive.

package/.agents/skills/forge-agent-fabric/scripts/fabric.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync, existsSync } from 'node:fs';
+import { dirname, resolve, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+// Runtime identity is independent of the target project: no cwd from runtime config.
+const skillRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+try {
+  const args = process.argv.slice(2);
+  let project = process.cwd();
+  const index = args.indexOf('--project');
+  if (index >= 0) {
+    if (!args[index + 1]) throw new Error('--project requires a target directory');
+    project = args[index + 1];
+    args.splice(index, 2);
+  }
+  const git = spawnSync('git', ['-C', project, 'rev-parse', '--show-toplevel'], { encoding: 'utf8', windowsHide: true });
+  if (git.status !== 0) throw new Error(`Target must be a Git repository: ${project}`);
+  const cwd = realpathSync(git.stdout.trim());
+  let runtime = {};
+  const config = resolve(skillRoot, 'runtime.json');
+  if (existsSync(config)) runtime = JSON.parse(readFileSync(config, 'utf8'));
+  let cliPath = process.env.FORGE_FABRIC_CLI || runtime.cliPath;
+  if (!cliPath) {
+    const lookup = spawnSync(process.platform === 'win32' ? 'where.exe' : 'which', ['forge'], { encoding: 'utf8', windowsHide: true });
+    const candidates = lookup.stdout?.trim().split(/\r?\n/).filter(Boolean) || [];
+    for (const candidate of candidates) {
+      const bin = realpathSync(candidate);
+      const guesses = [bin, resolve(dirname(bin), 'node_modules/forgeos/bin/forge.mjs')];
+      cliPath = guesses.find((path) => path.endsWith('.mjs') && existsSync(path));
+      if (cliPath) break;
+    }
+  }
+  if (!cliPath || !isAbsolute(cliPath) || !existsSync(cliPath)) {
+    throw new Error('Forge runtime not found. Install this skill with --runtime <absolute forge.mjs>, or set FORGE_FABRIC_CLI to that absolute file.');
+  }
+  const result = spawnSync(runtime.nodeExecutable || process.execPath, [realpathSync(cliPath), 'fabric', ...args], {
+    cwd, stdio: 'inherit', windowsHide: true,
+  });
+  if (result.error) throw result.error;
+  process.exitCode = result.status ?? 1;
+} catch (error) {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+}

package/AGENTS.md

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.67 input=cad72fb61cedf1a3702763e37d3d5706a149a8719284ec9090a960aa3a4e1e61 content=721818a6f9a664aa898092d4aa5cd68cbbd8ad6e150c7d3ad3ef785a2e3fcf53
+// @forge-generated generator=0.1.0-alpha.68 input=eb85ce79777e8854119a312edd29262099578bdd5f8be82c03b5f0caae80f391 content=721818a6f9a664aa898092d4aa5cd68cbbd8ad6e150c7d3ad3ef785a2e3fcf53
 # AGENTS.md
 
 <!-- forge-generated:start -->

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # forgeos
 
+## 0.1.0-alpha.68
+
+### Patch Changes
+
+- [`3d41af7`](https://github.com/Stahldavid/forge/commit/3d41af7b4580cd86618a7c76a3ac33b41e495e43) Thanks [@Stahldavid](https://github.com/Stahldavid)! - Make Agent Fabric reusable across Git repositories from the original Codex chat. Distribute a portable personal skill and installer, discover and reuse per-project owners, route MCP calls by registered project identity, and apply optional project environment and concurrency defaults. Harden Windows lock reads and owner startup failures, and exercise isolated execution outside the Forge checkout.
+
 ## 0.1.0-alpha.67
 
 ### Patch Changes

package/docs/agent-fabric.md

@@ -11,7 +11,15 @@ Codex executes the steps with its native tools; the scheduler does not start mod
 continue execution when the host is closed. The
 [detailed implementation and operation plan](./architecture/agent-fabric/CODEX_DYNAMIC_WORKFLOWS.md)
 documents both contracts, evidence provenance and the remaining acceptance work.
-The project skill is `.agents/skills/forge-agent-fabric/SKILL.md`.
+The portable skill is `.agents/skills/forge-agent-fabric/SKILL.md`. Install it once
+with `forge fabric install-skill --json` (or `node bin/forge.mjs fabric install-skill --json`
+in the framework checkout). It then operates in other Git repositories through a shared
+runtime, with one owner per repository and no Forge application dependency.
+Use `fabric doctor`, `fabric ensure-owner`, and optionally `fabric project-register`
+for explicit MCP routing by projectId. Hooks are optional. A project may declare
+environment/concurrency defaults and suggested checks in `.forge/fabric.json`.
+The [portable project plan](./architecture/agent-fabric/PORTABLE_PROJECTS_PLAN.md)
+describes isolation, installation, recovery and validation.
 
 ```bash
 node bin/forge.mjs fabric capabilities --json

package/docs/architecture/agent-fabric/PORTABLE_PROJECTS_PLAN.md

@@ -0,0 +1,136 @@
+# Agent Fabric across repositories
+
+## Outcome and boundaries
+
+The existing Codex App conversation remains the interface. One personal skill teaches
+Codex to prepare, execute, observe and resume Fabric workflows in the current project.
+The Forge runtime is shared; each Git repository has its own owner, state and isolated
+worker clones. Projects do not need a Forge application manifest or a Forge dependency.
+Windows and WSL copies are separate projects; this integration never migrates or syncs them.
+Owner startup does not start a model. Managed Codex workers use the host's configured
+Codex authentication and can consume its allowance. Local publication applies validated
+files; commit, push, npm release and deployments remain separately scoped actions.
+
+## 1. Portable skill and distribution
+
+Maintain the skill at `.agents/skills/forge-agent-fabric`, include it and its installer
+in the npm package, and make its protocol reference self-contained. Install once with
+`forge fabric install-skill --json` from any directory; add `--dry-run` to preview.
+The underlying `node scripts/install-agent-fabric-skill.mjs` also supports custom
+destination/runtime and explicit replacement; default destination is
+`~/.agents/skills/forge-agent-fabric`. Installed `runtime.json` stores the absolute
+Node executable and Forge CLI path. The helper resolves the target Git root and invokes
+the runtime with that root as cwd, without shell interpolation. An environment override
+and installed CLI fallback support different hosts. Runtime updates require reinstalling
+the skill to update the selected path/version; no implicit remote downloads occur.
+
+The installer stages changes, preserves unknown existing skills unless explicitly replaced,
+backs up replacements outside skill discovery, and reports unchanged installations.
+Installing a skill neither registers all local repositories nor installs hooks.
+
+## 2. Project identity and registration
+
+`fabric project-register [--project-id <id>] --json` resolves the current directory to
+the canonical Git toplevel and verifies HEAD. Default ids combine a readable directory
+name with a root digest, so equal names in different directories do not collide.
+`fabric project-list --json` reads the personal registry at
+`~/.forge/agent-fabric/projects.json`. Registration uses a bounded exclusive lock and
+atomic file replacement. Conflicting ids/roots and malformed or symlinked registry
+files are rejected. A registered path is resolved again before dispatch; moved/replaced
+roots cannot silently redirect an existing project id. Non-Git/empty repositories need
+initialization and an initial commit before managed cloning can run.
+
+The registry is host-local. No project credentials, owner bearer tokens or source contents
+are stored there. Registration is explicit and does not discover every directory on disk.
+
+## 3. Owner lifecycle and diagnostics
+
+`fabric doctor --json` resolves the Git root, reads optional settings, checks SDK availability,
+attempts a bounded `codex login status`, and authenticates any existing owner. It neither
+starts workers nor creates an owner. An unverified login is reported rather than inferred.
+`fabric ensure-owner --json` reuses an authenticated owner or starts `fabric serve` hidden
+and detached with cwd set to this root. Logs and endpoint metadata stay under
+`.forge/local/agent-fabric/`. Startup uses a per-project exclusive lock and bounded wait.
+Only its own newly spawned process may be stopped if startup times out; unknown live
+processes are not killed. An unreachable live endpoint requires diagnosis instead of
+starting another database owner. Startup locks surviving a crash are recovered only
+after their recorded process demonstrably exits, with serialized recovery and a byte
+readback. Live, malformed or unverified locks require inspection; they are never erased
+solely because a timer elapsed.
+If a process dies during recovery itself, its `.recovery` guard can require manual
+inspection after confirming that guard's process exited; diagnostics name both files.
+
+Authenticated health checks expose root and pid, never the endpoint token. Existing owners
+from the previous release are recognized through a read-only managed status probe.
+The owner remains an ordinary local process: restarting the machine requires starting it
+again; no OS service or periodic wakeup is installed.
+
+## 4. Optional project profile
+
+`.forge/fabric.json` is a small declarative file, not a Forge app configuration:
+
+```json
+{
+  "schemaVersion": 1,
+  "maxConcurrency": 2,
+  "environment": { "mode": "auto", "ignoreScripts": true, "timeoutMs": 120000 },
+  "verificationCommands": [["node", "--test"]]
+}
+```
+
+The shared managed request transport merges environment/concurrency defaults into
+`run-start`; explicit request values win. The profile does not change existing runs or
+silently append verification nodes. The skill reads suggested argv arrays and selects
+checks appropriate to the actual task. This avoids disguising executable project scripts
+as configuration reads. Unknown fields, excessive files, symlinks and invalid values
+are rejected. Node dependency preparation continues to use lockfiles and isolated copies;
+other stacks need explicit workflow commands and available host tooling. No universal
+Python/Go/Java provisioning is implied. Credentials and .env files are not copied merely
+because a profile exists.
+
+## 5. One MCP, multiple projects
+
+Keep the shared runtime's `mcp serve` entrypoint. Add `fabric_project_register`,
+`fabric_project_list`, `fabric_project_doctor`, and `fabric_owner_start`. Fabric tools
+accept an optional top-level `projectId`. The router resolves registered ids, removes
+the routing field before backend validation, then forwards to that root's owner.
+Explicitly routed responses include `projectContext: { id, root }` for readback.
+Calls without projectId retain the existing default workspace for compatibility.
+Hooks and non-Fabric agent-memory tools remain bound to the configured default workspace.
+Run calls cannot supply an arbitrary root. The skill must use explicit projectId outside
+the default workspace, or use CLI with the current Git root as cwd.
+
+MCP configuration remains one shared runtime entry. Restart/reconnect the Codex tool
+session to discover a changed tool catalog; use the skill's CLI helper immediately while
+the current conversation still has its old catalog. Do not claim tools are loaded until
+they appear. Do not change unrelated MCP entries or weaken authentication to add routing.
+
+## 6. Native chat flow
+
+1. User requests Agent Fabric work in a project; Codex reads its AGENTS.md and task scope.
+2. Skill helper resolves the root and runs capabilities/doctor.
+3. Register only this project when MCP routing is needed, then ensure its owner.
+4. Build a managed DAG with explicit scopes, implementers, independent reviewer and checks.
+5. Dispatch through the CLI or loaded MCP tools, using bounded waits and durable cursors.
+6. Replan from observed results while preserving required review/verification obligations.
+7. Reconcile uncertain attempts after interruption; do not repeat effects blindly.
+8. Read final project/run identity and evidence, then report actual results in the same chat.
+
+SDK worker threads are separate executions; they are not newly created Codex App sidebar
+conversations. This workflow does not require the user to operate a separate dashboard.
+
+## 7. Validation and delivery
+
+Validate registry contention, duplicate names/ids, nested cwd resolution, unknown/moved
+roots, profile defaults and explicit overrides, owner authentication/start/reuse, MCP
+routing into a second real Git repository, and hook isolation. Exercise the skill installer
+against a temporary personal directory and its helper against the real runtime. Run an
+observed command workflow in an external fixture without dispatching paid Codex models.
+Run generation/check, targeted Fabric tests, typecheck/lint and the framework verifier.
+Install the personal skill only after these checks; register Forge explicitly for current
+MCP routing. Preserve existing auth, other skills, MCP configuration and unrelated files.
+
+An external command pilot proves routing, cloning, execution and state readback. It does
+not itself prove a new paid SDK implementation/review round, production deployment or
+human acceptance. Package inclusion is checked separately from npm publication; this
+implementation task does not require publishing a new release.

package/docs/architecture/agent-fabric/README.md

@@ -0,0 +1,153 @@
+# Forge Agent Fabric — Architecture Governance
+
+This directory is the governance record for the Forge Agent Fabric architecture baseline.
+It is deliberately separate from `docs/agent-fabric.md`, which describes the executable
+P0a implementation surface.
+
+## Governance package
+
+| Record | Purpose |
+| --- | --- |
+| [`S1.0B1_DECISION_FREEZE.md`](./S1.0B1_DECISION_FREEZE.md) | Freezes the architecture decisions, vocabulary, invariants, boundaries, and deferred scope that later slices must preserve or explicitly supersede. |
+| [`S1.0B2_EVIDENCE_FREEZE.md`](./S1.0B2_EVIDENCE_FREEZE.md) | Freezes the evidence proving the accepted P0a baseline and maps evidence to the frozen decisions/invariants. |
+| [`P0A_ACCEPTANCE_RECORD.md`](./P0A_ACCEPTANCE_RECORD.md) | Records exactly what was accepted when P0a was merged, what was not accepted, and the applicability/supersession rules. |
+| [`S1.1_SCOPE_AND_GATE.md`](./S1.1_SCOPE_AND_GATE.md), [`S1.1_CONFORMANCE_PLAN.md`](./S1.1_CONFORMANCE_PLAN.md) | Adopted planning inputs for the normative kernel; historical planning assessments remain intact. |
+| [`S1.1_NORMATIVE_KERNEL.md`](./S1.1_NORMATIVE_KERNEL.md), [`S1.1_CONFORMANCE_MATRIX.md`](./S1.1_CONFORMANCE_MATRIX.md) | Adopted operation rules, invariant traceability, conformance obligations and clarification register. |
+| [`S1.1_ADOPTION_RECORD.md`](./S1.1_ADOPTION_RECORD.md) | Records the exact reviewed head, evidence and merge that adopted S1.1; explains retained candidate wording in historical artifacts. |
+| [`S1.2_SCOPE_AND_GATE.md`](./S1.2_SCOPE_AND_GATE.md), [`S1.2_DESIGN_PLAN.md`](./S1.2_DESIGN_PLAN.md) | Adopted scope and delivery plan for the reference implementation design. |
+| [`S1.2_REFERENCE_IMPLEMENTATION_DESIGN.md`](./S1.2_REFERENCE_IMPLEMENTATION_DESIGN.md), [`S1.2_IMPLEMENTATION_TRACEABILITY.md`](./S1.2_IMPLEMENTATION_TRACEABILITY.md), [`S1.2_DESIGN_DECISIONS.md`](./S1.2_DESIGN_DECISIONS.md) | Adopted reference implementation design; 24 operation mappings, 35 invariant mappings, 16 event-family mappings and preserved S12-F01/F02 history. |
+| [`S1.2_ADOPTION_RECORD.md`](./S1.2_ADOPTION_RECORD.md) | Records the exact reviewed head, checks, repair-aware evidence and merge that completed S12-D12 and adopted S1.2. |
+| [`S1.3_SCOPE_AND_GATE.md`](./S1.3_SCOPE_AND_GATE.md), [`S1.3_CONFORMANCE_PLAN.md`](./S1.3_CONFORMANCE_PLAN.md) | Adopted S1.3 Proof & Conformance planning package; S13-P08 complete. It authorized only the limited S1.3-A evidence/reproduction stage, not new tooling or P0b. |
+| [`S1.3_EVIDENCE_CATALOG.md`](./S1.3_EVIDENCE_CATALOG.md), [`S1.3_CONFORMANCE_MATRIX.md`](./S1.3_CONFORMANCE_MATRIX.md), [`S1.3_REPRODUCTION_PROTOCOL.md`](./S1.3_REPRODUCTION_PROTOCOL.md), [`S1.3_GAP_AND_TOOLING_REGISTER.md`](./S1.3_GAP_AND_TOOLING_REGISTER.md) | Adopted S1.3-A Evidence Registry & Reproduction Baseline: stable evidence/gap IDs, 24 OP / 35 I / 16 event cross-index, reproduction rules and tooling-need decisions; historical candidate wording is preserved inside the reviewed artifacts. |
+| [`S1.3_A_ADOPTION_RECORD.md`](./S1.3_A_ADOPTION_RECORD.md) | Records the exact reviewed head, exact-SHA gates, preserved FAIL/INCONCLUSIVE observations and merge that completed S13-A12 and adopted S1.3-A. |
+| [`S1.3_FINAL_CLOSURE_RECORD.md`](./S1.3_FINAL_CLOSURE_RECORD.md) | Adopted final S1.3 closure supplement. It binds post-S1.3-A evidence/repairs while preserving historical GAP-002/GAP-008 limitations and establishes the boundary to P0b. |
+| [`P0B_SCOPE_AND_GATE.md`](./P0B_SCOPE_AND_GATE.md) | Adopted planning scope for the first bounded nondeterministic P0b vertical. Historical proposal wording in that record remains as authored. |
+| [`P0B_A_MODEL_ADAPTER.md`](./P0B_A_MODEL_ADAPTER.md), [`P0B_A_ADOPTION_RECORD.md`](./P0B_A_ADOPTION_RECORD.md) | P0b-A implementation description and exact reviewed-head adoption evidence, including the authorized keyless local Ollama smoke. |
+| [`CODING_AGENT_DELIVERY_PLAN.md`](./CODING_AGENT_DELIVERY_PLAN.md) | Proposed ordered local-first delivery plan for MCP clients and a keyless coding worker; it does not adopt a new runtime capability. |
+| [`P0B_B_LOCAL_CODING_SCOPE.md`](./P0B_B_LOCAL_CODING_SCOPE.md) | Candidate scope and gates for a trusted-repository, single-owner MCP and local Ollama coding pilot; no runtime adoption claim. |
+
+## Baseline coordinates
+
+- Repository: `Stahldavid/forge`
+- Accepted implementation head: `bfd2639579e650d4ad38ec1a81dbd55a5d68865e`
+- Merge commit on `main`: `8972496f09727456b8b9f3ceafc386beab5f39d0`
+- PR: `#9 — feat: add Forge Agent Fabric P0a protocol kernel`
+- PR merged: `2026-09-08T09:26:36Z`
+- Pre-P0a base: `6f54ee728761bf91ff65465d798286d6f47fbe67`
+
+The merge commit has the reviewed P0a head as its second parent. This means the accepted
+implementation tree is traceable directly from `main` without relying on an external
+branch remaining available.
+
+## Status model
+
+| Record / stage | Adoption event | State |
+| --- | --- | --- |
+| P0a executable acceptance | [PR #9](https://github.com/Stahldavid/forge/pull/9), `8972496f09727456b8b9f3ceafc386beab5f39d0` | Accepted |
+| S1.0B1/B2 and P0a acceptance record | [PR #11](https://github.com/Stahldavid/forge/pull/11), `7a99ec5ceb2bdd51c83790fd84b23e534be52806` | Adopted |
+| S1.1 scope and conformance plan | [PR #12](https://github.com/Stahldavid/forge/pull/12), `3a0ce40ffe31555709d213bf06d674c62f28ad32` | Adopted planning input |
+| S1.1 kernel and conformance matrix | [PR #13](https://github.com/Stahldavid/forge/pull/13), `4b796f49c480d782ec7e069f8eb5f7eae841876a` | Adopted; G-14 complete |
+| S1.2 scope and gate | [PR #14](https://github.com/Stahldavid/forge/pull/14), `d1e6a1bb605527f242b7a6fb6fa05d6ff3561f92` | Adopted planning input; S12-P06 complete |
+| S12-F01 compatible resource-rejection repair | [PR #15](https://github.com/Stahldavid/forge/pull/15), `d9275f4773c1082a993ffaf7b6a58d15eb139246` | Adopted separately; reviewed head `16157c8bd59feecef6aa31692ba90a0d94f84307` |
+| S12-F02 compatible identifier-dictionary repair | [PR #17](https://github.com/Stahldavid/forge/pull/17), `2ca5ba7d261cf4001aa755581caa4b29de109b35` | FIXED_AND_ADOPTED separately; reviewed head `a832e29a3e8c757249eb8a59b7774d6521b4853e` |
+| S1.2 complete reference design | [PR #16](https://github.com/Stahldavid/forge/pull/16), `d2f426b1577d457bc6609c4d8e88ef7a055a1a23` | `ADOPTED`; S12-D12 complete; reviewed head `a2ac1769ac74fe9f7a87558a27332aa7c2a95114` |
+| S1.3 scope and conformance plan | [PR #18](https://github.com/Stahldavid/forge/pull/18), `801c2192e64652ade19a642b2f09f8660963c74f` | `ADOPTED`; S13-P08 complete; reviewed head `c694e9091bc1211b27d7e5e934ff4b9905e6ae89` |
+| Delta semantic timeline test timeout/cleanup | [PR #20](https://github.com/Stahldavid/forge/pull/20), `92c470ae2319aed9bde734d4506767677abe5a3c` | Adopted separately; reviewed head `0c8fe25d65ff5619395f3cf1f24635ba99a8e34c`; test-only, no Agent Fabric semantic change |
+| S1.3-A evidence/reproduction baseline | [PR #19](https://github.com/Stahldavid/forge/pull/19), `de9449648d821086db3d6f214c1a39cd4c659c7e` | `ADOPTED`; S13-A12 complete; reviewed head `b48a8fb4d77a1d8f5df7d9d523623a2037966da0` |
+| S1.3 final closure | [PR #43](https://github.com/Stahldavid/forge/pull/43), `f29b717f496b7edcd74e3f230c962e568fd0e5d2` | `ADOPTED`; reviewed head `36a6c75dfcc2c59e33fb04a8dfb9ce95da10f2ed`; adopted tree `49677d9979c2652c96f1cc4e0f2f82a17cb10f8e` |
+| P0b bounded model-adapter scope | [PR #46](https://github.com/Stahldavid/forge/pull/46), `490c2b54a2a354cb38b0f527c6a3f9372f703ff5` | Adopted planning input for P0b-A only |
+| P0b-A bounded model adapter | [PR #52](https://github.com/Stahldavid/forge/pull/52), `de3e1d5c97448823792bac1fcb71ab16e877ebab` | Adopted experimental runtime slice; reviewed head `ec37aeaa1c293d63e98de0b523fc2815761bc3dd` |
+
+The adopted S1.3 planning coordinate remains
+`main@801c2192e64652ade19a642b2f09f8660963c74f`. The separately adopted PR #20 moved the
+repository/reproduction baseline to `main@92c470ae2319aed9bde734d4506767677abe5a3c`; that
+movement was assessed under S13-A01. S1.3-A was subsequently adopted by PR #19 at
+`main@de9449648d821086db3d6f214c1a39cd4c659c7e`.
+
+S1.3 is formally closed by PR #43 at
+`main@f29b717f496b7edcd74e3f230c962e568fd0e5d2`. The closure preserves GAP-002 and GAP-008 as
+historical/nonblocking limitations, closes GAP-001 and GAP-009 through separately adopted
+evidence, and keeps GAP-003…007 within their previously adopted applicability boundaries.
+Candidate/planning labels in exact historical source artifacts remain preserved as authored;
+adoption merges and later supplements establish subsequent state.
+
+The P0b Scope & Gate was adopted through PR #46 over the closed S1.3 baseline. It authorized
+implementation work only for P0b-A. PR #52 separately adopted the bounded model-invocation
+adapter after exact-head CI/security checks, a keyless live Ollama smoke, independent review
+and an explicitly authorized merge. The adoption record retains those coordinates and limits.
+
+After adoption, changes must not silently rewrite history. A material change to a frozen
+architecture decision requires a new superseding decision record that identifies:
+
+1. the decision/invariant being superseded;
+2. the reason for the change;
+3. compatibility and migration impact;
+4. new evidence and conformance obligations;
+5. the exact commit at which the new decision becomes applicable.
+
+Corrections that do not alter semantics (typos, links, formatting, evidence-location
+updates) may amend these files directly, but must not change the meaning of frozen
+invariants.
+
+## Precedence
+
+For the accepted P0a baseline, use this order when sources appear to disagree:
+
+1. accepted executable behavior at `main@8972496f09727456b8b9f3ceafc386beab5f39d0`;
+2. machine-readable schema and hardened replay/validation behavior in that baseline;
+3. `P0A_ACCEPTANCE_RECORD.md`;
+4. `S1.0B1_DECISION_FREEZE.md`;
+5. `S1.0B2_EVIDENCE_FREEZE.md`;
+6. `docs/agent-fabric.md`;
+7. older design notes, handoffs, experiments, or conversation history.
+
+This precedence rule prevents an older architecture note from overriding behavior that
+was explicitly implemented, adversarially reviewed, and accepted.
+
+S1.1 supplies the adopted operation-level specification of that same accepted behavior.
+Its adoption does not reverse this precedence or authorize a discrepancy with the frozen
+invariants. S1.2 supplies the adopted source/ownership/sequence mapping of that behavior;
+it cannot override S1.1 or turn an implementation accident into a normative rule. A
+conflict among source, freeze, kernel and adopted design requires explicit classification
+under the existing change rule.
+
+S1.3 evidence describes what was observed and how it can be reproduced. Evidence metadata,
+a runner, a formal model or a signature cannot manufacture runtime authority or silently
+change an `OP-*`/`I-*` obligation. The adopted S1.3-A baseline may classify gaps and
+recommend a future decision, but it cannot itself implement a repair/tool or erase a
+historical failed or inconclusive observation.
+
+P0b planning inherits that precedence. A model/provider adapter may extend execution, but
+cannot override the accepted deterministic authority/replay semantics merely because a live
+provider behaves differently or exposes additional capabilities.
+
+## Scope boundary
+
+The freeze does **not** declare the entire future Agent Fabric implemented or
+production-ready. It distinguishes three categories:
+
+- **ACCEPTED_P0A** — implemented, tested, independently reviewed, and merged;
+- **FROZEN_DIRECTION** — architecture direction that later slices must respect but that
+  is not fully implemented by P0a;
+- **DEFERRED** — intentionally outside the accepted baseline and requiring a future slice
+  and separate acceptance evidence.
+
+S1.2 — Reference Implementation Design is adopted. S1.3 planning and S1.3-A are adopted, and
+S1.3 is now formally closed through the final closure record.
+
+The closed S1.3 evidence package organizes evidence with stable IDs, separates historical
+acceptance from current reproduction/source mapping, preserves `PASS`/`FAIL`/`SKIPPED`/
+`NOT_APPLICABLE`/`BLOCKED`/`INCONCLUSIVE`, cross-indexes all 24 OP rules, 35 invariants and
+16 persisted event families, defines exact-SHA reproduction discipline and retains historical
+limitations without converting them into false green claims.
+
+A generic conformance runner, formal model checking, proof/evidence signing, cross-language
+or JCS conformance, machine-readable evidence automation, production retention, production
+persistence/recovery, consequential effects and the broader future Agent Fabric remain
+outside the accepted P0a/S1.3 baseline.
+
+The adopted P0b-A slice is limited to one real provider-backed bounded external inference
+behind the existing P0a permit/result boundary. It excludes tools/plugins/delegation,
+consequential target mutation, production persistence/outbox, recovery epochs, adaptive
+routing, persistent governed memory and plugin/evolution promotion. P0b-B and those broader
+capabilities have no adoption claim in this record.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgeos",
-  "version": "0.1.0-alpha.67",
+  "version": "0.1.0-alpha.68",
   "description": "Agent-native application framework and compiler for building Forge apps without a mandatory dashboard.",
   "type": "module",
   "license": "MIT",
@@ -11,9 +11,12 @@
     "!adapters/**/*.jar",
     "bin/",
     "scripts/field-test-forgeos.mjs",
+    "scripts/install-agent-fabric-skill.mjs",
+    ".agents/skills/forge-agent-fabric/",
     "docs/cair-protocol.md",
     "docs/forge-protocol.md",
     "docs/agent-fabric.md",
+    "docs/architecture/agent-fabric/PORTABLE_PROJECTS_PLAN.md",
     "examples/go-billing/",
     "examples/java-billing/",
     "!examples/**/target/**",
@@ -68,6 +71,7 @@
     "release:publish-alpha": "node scripts/publish-trusted-alpha.mjs",
     "release:publish-local-alpha": "node scripts/publish-local-alpha.mjs",
     "field:test": "node scripts/field-test-forgeos.mjs",
+    "fabric:install-skill": "node scripts/install-agent-fabric-skill.mjs",
     "forge": "node ./bin/forge.mjs",
     "forge:node": "node ./bin/forge.mjs",
     "forge:bun": "node ./bin/forge-bun.mjs src/forge/cli/main.ts",