forgeos 0.1.0-alpha.66 → 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/.npmignore

@@ -1,19 +1,19 @@
-# Package contents are primarily controlled by package.json "files".
-node_modules/
-.git/
-.github/
-.forge/
-tests/
-examples/
-adapters/**/target/
-examples/**/target/
-*.class
-*.jar
-**/*.class
-**/*.jar
-src/forge/_generated/**
-!src/forge/_generated/
-!src/forge/_generated/releaseManifest.json
-!src/forge/_generated/releaseManifest.ts
-*.tgz
-npm-debug.log*
+# Package contents are primarily controlled by package.json "files".
+node_modules/
+.git/
+.github/
+.forge/
+tests/
+examples/
+adapters/**/target/
+examples/**/target/
+*.class
+*.jar
+**/*.class
+**/*.jar
+src/forge/_generated/**
+!src/forge/_generated/
+!src/forge/_generated/releaseManifest.json
+!src/forge/_generated/releaseManifest.ts
+*.tgz
+npm-debug.log*

package/AGENTS.md

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.66 input=57341432921f2c43eddb033a05cc7ad25dabd9813fcf2fd64c67f74ae5f61859 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,25 @@
 # 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
+
+- [#68](https://github.com/Stahldavid/forge/pull/68) [`444d89a`](https://github.com/Stahldavid/forge/commit/444d89a1041f0005663ffa3f37611a0f2821022a) Thanks [@Stahldavid](https://github.com/Stahldavid)! - Keep Codex hook events available to Agent Memory through a local Delta owner.
+  Automatically resume the redacted hook queue, deduplicate events after a crash,
+  report queue freshness in CLI and MCP results, and distinguish real database
+  errors from an unverified PGlite lock file.
+
+- Add durable Codex SDK dynamic workflows driven from the original Codex chat, with isolated workers, dependency preparation, independent review, scoped artifact publication and explicit interruption recovery. Reduce duplicate CI checks and parallelize package validation while preserving release gates. Fix Windows hook subprocess diagnostics and managed execution races.
+  Upgrade Changesets to v3 with compatible prerelease checks, update the Next.js template to 16.3.8, and close temporary Delta owners before packed-package smoke cleanup on Windows.
+
+- Normalize POSIX process start timestamps to UTC so live Delta owners and queue leases are not mistaken for reused PIDs when the runtime and host use different time zones.
+
 ## 0.1.0-alpha.66
 
 ### Patch Changes

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 ForgeOS contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 ForgeOS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.