worktrust 0.10.12 → 0.10.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md CHANGED
@@ -16,6 +16,11 @@ the variables your client sets, do not run it through another shell, and do not
16
16
  The session hook and the MCP door are started by your client itself and are meant to run; leave their configuration as
17
17
  the person set it. This does not authorize an agent to invoke `preserve` through another entry point. Even `status`
18
18
  can inspect local evidence and check the registry; do not run it as a generic repository inventory command.
19
+ The new `orchestration report --file` command reads a person's explicitly selected agent metadata
20
+ and is person-only too. Repository maintenance tests may use synthetic recordings. Python SDK
21
+ events remain application reports: do not manufacture security events, verification or success,
22
+ and do not describe them as independently measured capability. See `docs/AGENT-OBSERVATIONS.md`
23
+ in the monorepo for the contract and the private Sources page.
19
24
 
20
25
  ## Do not report work you did not see
21
26
 
package/README.md CHANGED
@@ -7,7 +7,7 @@ record of the work you do with AI without anyone reading that work: it receives
7
7
  npx worktrust@latest
8
8
  ```
9
9
 
10
- **The only official package** is `worktrust`, published by the npm account **worktrustio** with
10
+ **The official npm package** is `worktrust`, published by the npm account **worktrustio** with
11
11
  provenance from this repository (github.com/fhomey/worktrust-cli). Check it on npmjs.com before you run
12
12
  it; a package of another name or from another publisher is not ours. Without npm, the same script runs
13
13
  from WorkTrust's own site:
@@ -16,6 +16,39 @@ from WorkTrust's own site:
16
16
  curl -fsSO https://app.worktrust.io/counter/worktrust.mjs && node worktrust.mjs
17
17
  ```
18
18
 
19
+ **Python tool runners:** this repository also builds `worktrust` for `uvx` and `pipx` from the
20
+ same measurement modules. Native wheels (0.10.13+) include a pinned official Node runtime,
21
+ so that route needs no separate Node/npm installation. See the
22
+ [Python distribution](https://github.com/fhomey/worktrust-cli/tree/main/python) for supported
23
+ platforms and installation commands, and the official [PyPI project](https://pypi.org/project/worktrust/)
24
+ for published versions. npm and Python versions are checked together.
25
+
26
+ ```sh
27
+ uvx worktrust@latest preserve
28
+ pipx run --no-cache worktrust preserve
29
+ ```
30
+
31
+ Omit `preserve` to connect your computer. These runners install and invoke the same CLI;
32
+ they do not automatically instrument Python applications or measure different activity.
33
+
34
+ Connecting through the Python package installs the runtime and engine in an immutable directory
35
+ under `~/.worktrust/installations/`; client hooks use that persistent path, so clearing a tool-runner
36
+ cache does not break the coupling. Updates retain older installations for running clients.
37
+ Run `worktrust disconnect` before removing an installed Python tool if you also want to remove its
38
+ WorkTrust coupling. Disconnect removes the key and client wiring; it leaves runtime files in place.
39
+
40
+ **Agent observations (requires 0.10.14+):** the optional Python
41
+ `worktrust_cli.telemetry` SDK lets an application explicitly record parent/child runs, its own
42
+ token counters, token budgets, checks and security events in a local file. The shared engine
43
+ inspects it with `worktrust orchestration report --file agent-events.jsonl`, without uploading.
44
+ The private platform import is Sources → Agent teams when that platform change is deployed.
45
+ These are application reports, not human hours or independently verified outcomes. Installing
46
+ through npm, uvx or pipx alone does not instrument agents. See the Python README for the opt-in
47
+ SDK, fixed metadata fields, consent and local deletion. Install `worktrust>=0.10.14` in the
48
+ agent application's own Python environment to import the SDK; a uvx/pipx tool environment
49
+ is separate. Check the registry for availability: a GitHub release awaiting approval is not
50
+ a completed npm or PyPI publication.
51
+
19
52
  **No account? Keep your history anyway.** Claude Code and Gemini CLI delete their sessions after 30
20
53
  days by default, and a deleted session can never be measured again. `npx worktrust@latest preserve` shows what
21
54
  each AI app on this computer keeps, keeps it longer on your yes, and writes a local, metadata-only
package/SECURITY.md CHANGED
@@ -71,3 +71,29 @@ Check the particular published version's attestation and compare its contents to
71
71
  relying on those properties. A manifest flag or matching version string alone is not proof that an
72
72
  artifact was built from reviewed source. `npm audit signatures` can inspect an installed dependency
73
73
  tree; verification coverage and failures must be reported for that actual installation.
74
+
75
+
76
+ ## Python distribution and explicit agent observations
77
+
78
+ The official [PyPI package](https://pypi.org/project/worktrust/) runs the same measurement
79
+ modules as npm. Supported wheels include the pinned Node runtime; invocation does not download
80
+ Node, fall back to PATH or relay to a newer npm version. Package-manager installation and
81
+ upgrades can contact registries. Use the README for platform requirements and update commands.
82
+
83
+ From 0.10.14, the optional Python recorder writes explicitly supplied UUIDs, dates, fixed event
84
+ categories and counts to a newly chosen local file, with `consent=True`. It makes no network
85
+ requests and does not discover agents or inspect their prompts, outputs, model names or code.
86
+ The local `orchestration report --file` command also sends nothing. Recordings are bounded;
87
+ existing files and symlink paths are refused. The requested file mode is 0600; Windows folder
88
+ ACLs and other processes running as the same user remain outside that protection.
89
+
90
+ These observations are application reports, including reported checks and security events.
91
+ They do not independently establish successful outcomes, prompt-injection resistance, human
92
+ hours or capability. Parent/child elapsed time includes waiting and must not be summed as
93
+ human work. Missing token coverage remains unknown; providers must supply exclusive deltas.
94
+
95
+ The separate private platform import requires a deployed platform feature and explicit browser
96
+ selection and consent. It is not an automatic SDK upload or an MCP submission. Deleting a local
97
+ recording does not erase a separately imported copy; delete that copy through the private app.
98
+ See the service [privacy policy](https://worktrust.io/privacy) and
99
+ [support](https://worktrust.io/support) for account data requests.
package/log-session.mjs CHANGED
@@ -1080,7 +1080,7 @@ if (flag("install")) {
1080
1080
  const settings = existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : {};
1081
1081
  // `--via <worktrust.mjs>`: the key lives in ~/.worktrust/key.json, so Claude Code runs the wrapper, which reads it and starts this hook.
1082
1082
  const via = args.indexOf("--via") >= 0 ? args[args.indexOf("--via") + 1] : null;
1083
- const command = via ? `"${process.env.WORKTRUST_NODE || process.execPath}" "${via}" hook` : `node ${home}`;
1083
+ const command = `"${process.env.WORKTRUST_NODE || process.execPath}" "${via ?? home}"${via ? " hook" : ""}`;
1084
1084
  settings.hooks ??= {};
1085
1085
  for (const event of HOOK_EVENTS) settings.hooks[event] ??= [];
1086
1086
  // A WIRING THAT POINTS SOMEWHERE ELSE IS REPAIRED, NOT LEFT. An earlier install wired whatever
@@ -0,0 +1,155 @@
1
+ // GENERATED by scripts/build-orchestration-evidence.mjs; edit packages/core/src/orchestration-contract.ts.
2
+ /** Explicit application reports, never verified human work. No names, prompts or provider payloads. */
3
+ export const ORCHESTRATION_LIMITS = { bytes: 262144, lineBytes: 4096, events: 2048, runs: 64, elapsed: 604800000, tokens: 1000000000 };
4
+ export const AGENT_ROLES = ["orchestrator", "worker", "reviewer", "researcher", "verifier", "other"];
5
+ export const AGENT_TASK_KINDS = ["build", "fix", "review", "research", "decide", "other"];
6
+ export const SECURITY_EVENT_CODES = ["injection_candidate_seen", "injection_ignored", "injection_followed", "untrusted_instruction_escalated", "external_instruction_override_attempt", "suspicious_tool_blocked"];
7
+ export const INTERVENTION_CODES = ["challenge", "reframe", "alternative", "verification_request"];
8
+ export const USAGE_KEYS = ["input_uncached_tokens", "cache_read_tokens", "cache_write_tokens", "output_tokens"];
9
+ const uuid = (value) => typeof value === "string" && value.length === 36 && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(value);
10
+ const integer = (value, max, min = 0) => typeof value === "number" && Number.isInteger(value) && value >= min && value <= max;
11
+ const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
12
+ const fail = () => { throw new Error("invalid_orchestration_recording"); };
13
+ const exact = (row, required, optional = []) => {
14
+ if (required.some((key) => !Object.hasOwn(row, key)) || Object.keys(row).some((key) => !required.includes(key) && !optional.includes(key)))
15
+ fail();
16
+ };
17
+ const includes = (list, value) => typeof value === "string" && list.includes(value);
18
+ const bytes = (text) => new TextEncoder().encode(text).length;
19
+ /** Stable identity for duplicate comparison, also independent of JSON object key order. */
20
+ export function orchestrationCanonical(value) {
21
+ if (Array.isArray(value))
22
+ return `[${value.map(orchestrationCanonical).join(",")}]`;
23
+ if (object(value))
24
+ return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${orchestrationCanonical(value[key])}`).join(",")}}`;
25
+ return JSON.stringify(value) ?? fail();
26
+ }
27
+ function header(row) {
28
+ if (row.schema !== 1 || !uuid(row.session_id) || typeof row.started_at !== "string" || !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(row.started_at))
29
+ fail();
30
+ const date = new Date(row.started_at);
31
+ if (!Number.isFinite(date.getTime()) || date.toISOString() !== row.started_at)
32
+ fail();
33
+ }
34
+ function event(value) {
35
+ if (!object(value) || bytes(JSON.stringify(value)) > ORCHESTRATION_LIMITS.lineBytes)
36
+ fail();
37
+ const row = value;
38
+ const base = ["event_id", "run_id", "sequence", "elapsed_ms", "kind"];
39
+ if (!uuid(row.event_id) || !uuid(row.run_id) || !integer(row.sequence, ORCHESTRATION_LIMITS.events, 1) || !integer(row.elapsed_ms, ORCHESTRATION_LIMITS.elapsed))
40
+ fail();
41
+ switch (row.kind) {
42
+ case "run_started":
43
+ exact(row, [...base, "agent_id", "agent_version", "role", "task_kind"], ["parent_run_id"]);
44
+ if (!uuid(row.agent_id) || !uuid(row.agent_version) || !includes(AGENT_ROLES, row.role) || !includes(AGENT_TASK_KINDS, row.task_kind) || (Object.hasOwn(row, "parent_run_id") && !uuid(row.parent_run_id)))
45
+ fail();
46
+ break;
47
+ case "run_finished":
48
+ exact(row, [...base, "status"]);
49
+ if (!includes(["succeeded", "failed", "cancelled"], row.status))
50
+ fail();
51
+ break;
52
+ case "usage":
53
+ exact(row, [...base, "scope"], USAGE_KEYS);
54
+ if (row.scope !== "own" || !USAGE_KEYS.some((key) => Object.hasOwn(row, key)) || USAGE_KEYS.some((key) => Object.hasOwn(row, key) && !integer(row[key], ORCHESTRATION_LIMITS.tokens)))
55
+ fail();
56
+ break;
57
+ case "budget":
58
+ exact(row, [...base, "token_limit"]);
59
+ if (!integer(row.token_limit, ORCHESTRATION_LIMITS.tokens, 1))
60
+ fail();
61
+ break;
62
+ case "security":
63
+ exact(row, [...base, "code", "source"]);
64
+ if (!includes(SECURITY_EVENT_CODES, row.code) || !includes(["client_report", "boundary_report"], row.source))
65
+ fail();
66
+ break;
67
+ case "verification":
68
+ exact(row, [...base, "result"]);
69
+ if (!includes(["passed", "failed"], row.result))
70
+ fail();
71
+ break;
72
+ case "intervention":
73
+ exact(row, [...base, "code"]);
74
+ if (!includes(INTERVENTION_CODES, row.code))
75
+ fail();
76
+ break;
77
+ default: fail();
78
+ }
79
+ // Reconstruct through JSON: no caller-owned references or getters reach storage/summary.
80
+ return JSON.parse(JSON.stringify(row));
81
+ }
82
+ /** Validates every event and graph edge. Reorders replay deterministically; repeated IDs must be identical. */
83
+ export function validateOrchestrationRecording(input) {
84
+ if (!object(input) || bytes(JSON.stringify(input)) > ORCHESTRATION_LIMITS.bytes)
85
+ fail();
86
+ const row = input;
87
+ exact(row, ["schema", "session_id", "started_at", "events"]);
88
+ header(row);
89
+ if (!Array.isArray(row.events) || row.events.length === 0 || row.events.length > ORCHESTRATION_LIMITS.events)
90
+ fail();
91
+ const unique = new Map();
92
+ for (const raw of row.events) {
93
+ const item = event(raw), prior = unique.get(item.event_id);
94
+ if (prior && orchestrationCanonical(prior) !== orchestrationCanonical(item))
95
+ fail();
96
+ unique.set(item.event_id, item);
97
+ }
98
+ const events = [...unique.values()].sort((a, b) => a.sequence - b.sequence);
99
+ const starts = new Map();
100
+ const finishes = new Set(), used = new Set(), budgets = new Set();
101
+ let previousSequence = 0, previousElapsed = 0;
102
+ for (const item of events) {
103
+ if (item.sequence !== previousSequence + 1 || item.elapsed_ms < previousElapsed)
104
+ fail();
105
+ previousSequence = item.sequence;
106
+ previousElapsed = item.elapsed_ms;
107
+ if (item.kind === "run_started") {
108
+ if (starts.has(item.run_id) || (item.parent_run_id && (!starts.has(item.parent_run_id) || finishes.has(item.parent_run_id))))
109
+ fail();
110
+ starts.set(item.run_id, item);
111
+ if (starts.size > ORCHESTRATION_LIMITS.runs)
112
+ fail();
113
+ }
114
+ else {
115
+ if (!starts.has(item.run_id) || finishes.has(item.run_id))
116
+ fail();
117
+ if (item.kind === "run_finished") {
118
+ // A parent cannot finish before its active children. Interrupted recordings keep it open.
119
+ if ([...starts.values()].some((start) => start.parent_run_id === item.run_id && !finishes.has(start.run_id)))
120
+ fail();
121
+ finishes.add(item.run_id);
122
+ }
123
+ if (item.kind === "usage")
124
+ used.add(item.run_id);
125
+ if (item.kind === "budget") {
126
+ if (budgets.has(item.run_id) || used.has(item.run_id))
127
+ fail();
128
+ budgets.add(item.run_id);
129
+ }
130
+ }
131
+ }
132
+ return { schema: 1, session_id: row.session_id, started_at: row.started_at, events };
133
+ }
134
+ /** JSONL is an explicit opt-in file; an incomplete last line is rejected, never silently truncated. */
135
+ export function parseOrchestrationJsonl(text) {
136
+ if (typeof text !== "string" || bytes(text) > ORCHESTRATION_LIMITS.bytes)
137
+ fail();
138
+ const lines = text.replace(/\r\n/g, "\n").split("\n");
139
+ if (lines.at(-1) === "")
140
+ lines.pop();
141
+ if (lines.length < 2 || lines.some((line) => !line || bytes(line) > ORCHESTRATION_LIMITS.lineBytes))
142
+ fail();
143
+ let rows;
144
+ try {
145
+ rows = lines.map((line) => JSON.parse(line));
146
+ }
147
+ catch {
148
+ return fail();
149
+ }
150
+ if (!object(rows[0]))
151
+ fail();
152
+ const first = rows[0];
153
+ exact(first, ["schema", "session_id", "started_at"]);
154
+ return validateOrchestrationRecording({ ...first, events: rows.slice(1) });
155
+ }
@@ -0,0 +1,59 @@
1
+ // GENERATED by scripts/build-orchestration-evidence.mjs; edit packages/core/src/orchestration-evidence.ts.
2
+ /** Descriptive application telemetry. No scoring, hiring inference or autonomous-to-human time conversion. */
3
+ import { USAGE_KEYS, validateOrchestrationRecording } from "./orchestration-contract.mjs";
4
+ export * from "./orchestration-contract.mjs";
5
+ function summarizeRun(start, events) {
6
+ const end = events.find((item) => item.kind === "run_finished");
7
+ const usages = events.filter((item) => item.kind === "usage");
8
+ const completeUsage = usages.length > 0 && usages.every((item) => USAGE_KEYS.every((key) => item[key] !== undefined));
9
+ const counts = Object.fromEntries(USAGE_KEYS.map((key) => [key, usages.reduce((sum, item) => sum + (item[key] ?? 0), 0)]));
10
+ const total = completeUsage ? USAGE_KEYS.reduce((sum, key) => sum + counts[key], 0) : null;
11
+ const input = counts.input_uncached_tokens + counts.cache_read_tokens + counts.cache_write_tokens;
12
+ const budget = events.find((item) => item.kind === "budget");
13
+ const checks = events.filter((item) => item.kind === "verification");
14
+ const security = {}, interventions = {};
15
+ for (const item of events) {
16
+ if (item.kind === "security")
17
+ security[item.code] = (security[item.code] ?? 0) + 1;
18
+ if (item.kind === "intervention")
19
+ interventions[item.code] = (interventions[item.code] ?? 0) + 1;
20
+ }
21
+ const limit = budget?.kind === "budget" ? budget.token_limit : null;
22
+ return {
23
+ run_id: start.run_id, ...(start.parent_run_id ? { parent_run_id: start.parent_run_id } : {}), agent_id: start.agent_id, agent_version: start.agent_version,
24
+ role: start.role, task_kind: start.task_kind, status: end?.kind === "run_finished" ? end.status : "incomplete", elapsed_ms: end ? end.elapsed_ms - start.elapsed_ms : null,
25
+ tokens_total: total, cache_share: completeUsage && input > 0 ? counts.cache_read_tokens / input : null, token_limit: limit,
26
+ budget_exceeded: total !== null && limit !== null ? total > limit : null,
27
+ verification: checks.length ? { passed: checks.filter((item) => item.kind === "verification" && item.result === "passed").length, failed: checks.filter((item) => item.kind === "verification" && item.result === "failed").length } : null,
28
+ security, interventions,
29
+ };
30
+ }
31
+ /** One engine for CLI and platform. Missing counters stay unknown; finished means reported, not accepted by a customer. */
32
+ export function summarizeOrchestration(input) {
33
+ const recording = validateOrchestrationRecording(input);
34
+ const starts = recording.events.filter((item) => item.kind === "run_started");
35
+ const runs = starts.map((start) => summarizeRun(start, recording.events.filter((item) => item.run_id === start.run_id)));
36
+ const allComplete = runs.every((run) => run.elapsed_ms !== null);
37
+ const boundaryCounts = new Map();
38
+ for (const item of recording.events) {
39
+ if (item.kind !== "run_started" && item.kind !== "run_finished")
40
+ continue;
41
+ boundaryCounts.set(item.elapsed_ms, (boundaryCounts.get(item.elapsed_ms) ?? 0) + (item.kind === "run_started" ? 1 : -1));
42
+ }
43
+ let active = 0, peak = 0, union = 0, previous = 0;
44
+ for (const [elapsed, delta] of [...boundaryCounts].sort((a, b) => a[0] - b[0])) {
45
+ if (active > 0)
46
+ union += elapsed - previous;
47
+ active += delta;
48
+ peak = Math.max(peak, active);
49
+ previous = elapsed;
50
+ }
51
+ return {
52
+ provenance: "application_reported", session_id: recording.session_id, started_at: recording.started_at, runs,
53
+ coverage: { runs: runs.length, complete_runs: runs.filter((run) => run.elapsed_ms !== null).length, usage_runs: runs.filter((run) => run.tokens_total !== null).length, events: recording.events.length },
54
+ elapsed_ms: allComplete ? union : null, agent_run_ms: allComplete ? runs.reduce((sum, run) => sum + (run.elapsed_ms ?? 0), 0) : null,
55
+ // A run rounded to zero milliseconds is below this clock's resolution, not proof of zero simultaneous runs.
56
+ peak_concurrency: allComplete && runs.every((run) => (run.elapsed_ms ?? 0) > 0) ? peak : null,
57
+ tokens_total: runs.every((run) => run.tokens_total !== null) ? runs.reduce((sum, run) => sum + (run.tokens_total ?? 0), 0) : null,
58
+ };
59
+ }
@@ -0,0 +1,28 @@
1
+ /** Explicit local metadata file only. No home discovery, credentials, uploads or clocks invented here. */
2
+ import { constants, openSync, closeSync, fstatSync, lstatSync, readSync } from "node:fs";
3
+ import { parseOrchestrationJsonl, summarizeOrchestration } from "./orchestration-evidence.mjs";
4
+
5
+ export function reportFile(args) {
6
+ if (args.length !== 3 || args[0] !== "report" || args[1] !== "--file" || !args[2]) {
7
+ process.stderr.write("Usage: worktrust orchestration report --file recording.jsonl\n");
8
+ process.exitCode = 1;
9
+ return;
10
+ }
11
+ let fd;
12
+ try {
13
+ const before = lstatSync(args[2]);
14
+ if (!before.isFile() || before.isSymbolicLink()) throw Error("invalid");
15
+ fd = openSync(args[2], constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
16
+ const info = fstatSync(fd);
17
+ if (!info.isFile() || info.size > 262144 || info.dev !== before.dev || info.ino !== before.ino) throw Error("invalid");
18
+ const bytes = Buffer.alloc(262145);
19
+ let length = 0, received;
20
+ do { received = readSync(fd, bytes, length, bytes.length - length, null); length += received; } while (received && length < bytes.length);
21
+ if (length > 262144) throw Error("invalid");
22
+ const recording = parseOrchestrationJsonl(new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, length)));
23
+ process.stdout.write(JSON.stringify(summarizeOrchestration(recording), null, 2) + "\n");
24
+ } catch {
25
+ process.stderr.write("Orchestration recording refused: use a regular, bounded file with valid metadata.\n");
26
+ process.exitCode = 1;
27
+ } finally { if (fd !== undefined) closeSync(fd); }
28
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "worktrust",
3
- "version": "0.10.12",
3
+ "version": "0.10.14",
4
4
  "description": "Couple this computer to WorkTrust: approve a code in your browser, and every AI app here reports what you built. Metadata only, no dependencies.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -20,11 +20,15 @@
20
20
  "stretch-evidence.mjs",
21
21
  "chat-exports.mjs",
22
22
  "stack-rules.mjs",
23
+ "runtime-install.mjs",
23
24
  "README.md",
24
25
  "SECURITY.md",
25
26
  "LICENSE",
26
27
  "AGENTS.md",
27
- "CLAUDE.md"
28
+ "CLAUDE.md",
29
+ "orchestration-contract.mjs",
30
+ "orchestration-evidence.mjs",
31
+ "orchestration-report.mjs"
28
32
  ],
29
33
  "engines": {
30
34
  "node": ">=18"
@@ -0,0 +1,64 @@
1
+ /** Immutable, owned runtime + engine installation for Python tool-runner caches.
2
+ * Called only after the person's connect/update confirmation. No network, credentials or measurement logic.
3
+ */
4
+ import { createHash, randomBytes } from "node:crypto";
5
+ import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
6
+ import { join } from "node:path";
7
+
8
+ const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
9
+ const regular = (path) => { const stat = lstatSync(path); if (!stat.isFile() || stat.isSymbolicLink()) throw Error("bundled installation requires regular files"); };
10
+ const directory = (path) => { const stat = lstatSync(path); if (!stat.isDirectory() || stat.isSymbolicLink()) throw Error("bundled installation requires owned directories, not symlinks"); };
11
+ const checkedBytes = (path) => { regular(path); return readFileSync(path); };
12
+
13
+ export function installRuntime(runtime, engine, home, moduleNames) {
14
+ directory(runtime); directory(engine); directory(home);
15
+ const descriptor = checkedBytes(join(runtime, "runtime.json"));
16
+ const manifest = JSON.parse(descriptor);
17
+ const executable = process.platform === "win32" ? "node.exe" : "node";
18
+ const target = `${process.platform === "win32" ? "win" : process.platform}-${process.arch}`;
19
+ if (manifest.platform !== target || manifest.executable !== executable || !/^\d+\.\d+\.\d+$/.test(manifest.version) || !/^[a-f0-9]{64}$/.test(manifest.archive_sha256)) throw Error("bundled runtime identity mismatch");
20
+ const names = [executable, "LICENSE"].sort();
21
+ if (!manifest.files || JSON.stringify(Object.keys(manifest.files).sort()) !== JSON.stringify(names) || JSON.stringify(readdirSync(runtime).sort()) !== JSON.stringify([...names, "runtime.json"].sort())) throw Error("bundled runtime file list mismatch");
22
+ const contents = new Map([["runtime/runtime.json", descriptor]]);
23
+ for (const name of names) {
24
+ const bytes = checkedBytes(join(runtime, name));
25
+ if (hash(bytes) !== manifest.files[name]) throw Error("bundled runtime integrity check failed");
26
+ contents.set(`runtime/${name}`, bytes);
27
+ }
28
+ if (!Array.isArray(moduleNames) || !moduleNames.includes("worktrust.mjs") || new Set(moduleNames).size !== moduleNames.length) throw Error("invalid engine module list");
29
+ for (const name of [...moduleNames].sort()) {
30
+ if (!/^[a-z][a-z0-9-]*\.mjs$/.test(name)) throw Error("invalid engine module name");
31
+ contents.set(`engine/${name}`, checkedBytes(join(engine, name)));
32
+ }
33
+ const identities = Object.fromEntries([...contents].map(([name, bytes]) => [name, hash(bytes)]));
34
+ const identity = Buffer.from(JSON.stringify(identities));
35
+ const installations = join(home, "installations"), installed = join(installations, hash(identity));
36
+ if (!existsSync(installations)) mkdirSync(installations, { mode: 0o700 });
37
+ directory(installations);
38
+ const verify = (place) => {
39
+ directory(place);
40
+ if (JSON.stringify(readdirSync(place).sort()) !== JSON.stringify(["engine", "installation.json", "runtime"])) throw Error("installed bundle file list mismatch");
41
+ if (!checkedBytes(join(place, "installation.json")).equals(identity)) throw Error("installed bundle identity mismatch");
42
+ for (const group of ["engine", "runtime"]) {
43
+ directory(join(place, group));
44
+ const expected = [...contents.keys()].filter(name => name.startsWith(`${group}/`)).map(name => name.slice(group.length + 1)).sort();
45
+ if (JSON.stringify(readdirSync(join(place, group)).sort()) !== JSON.stringify(expected)) throw Error("installed bundle file list mismatch");
46
+ }
47
+ for (const [name, digest] of Object.entries(identities)) if (hash(checkedBytes(join(place, name))) !== digest) throw Error("installed bundle integrity check failed");
48
+ };
49
+ if (existsSync(installed)) verify(installed);
50
+ else {
51
+ const temporary = join(installations, `.install-${process.pid}-${randomBytes(8).toString("hex")}`);
52
+ mkdirSync(temporary, { mode: 0o700 });
53
+ try {
54
+ mkdirSync(join(temporary, "engine"), { mode: 0o700 }); mkdirSync(join(temporary, "runtime"), { mode: 0o700 });
55
+ for (const [name, bytes] of contents) writeFileSync(join(temporary, name), bytes, { flag: "wx", mode: name === `runtime/${executable}` ? 0o755 : 0o600 });
56
+ writeFileSync(join(temporary, "installation.json"), identity, { flag: "wx", mode: 0o600 });
57
+ verify(temporary);
58
+ try { renameSync(temporary, installed); }
59
+ catch (error) { if (!existsSync(installed)) throw error; verify(installed); }
60
+ } finally { rmSync(temporary, { recursive: true, force: true }); }
61
+ }
62
+ // Existing immutable directories are never replaced, including executables used by Windows processes.
63
+ return { executable: join(installed, "runtime", executable), bridge: join(installed, "engine", "worktrust.mjs") };
64
+ }
package/worktrust.mjs CHANGED
@@ -70,7 +70,7 @@
70
70
  import { execFileSync, spawn } from "node:child_process";
71
71
  import { createHash, generateKeyPairSync, randomBytes, sign } from "node:crypto";
72
72
  import { createServer } from "node:http";
73
- import { chmodSync, closeSync, copyFileSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
73
+ import { chmodSync, closeSync, copyFileSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
74
74
  import { homedir, hostname, platform } from "node:os";
75
75
  import { dirname, join } from "node:path";
76
76
  import { createInterface } from "node:readline/promises";
@@ -83,14 +83,14 @@ const command = args.includes("--help") ? "help" : args.includes("--version") ?
83
83
  const flag = (name) => { const at = args.indexOf(`--${name}`); return at >= 0 ? args[at + 1] : undefined; };
84
84
  const has = (name) => args.includes(`--${name}`);
85
85
  /** This CLI's version, said to the door so the app can tell which computer runs an old one (check-cli-package holds it equal to package.json). */
86
- const CLI_VERSION = "0.10.12";
86
+ const CLI_VERSION = "0.10.14";
87
87
  const ORIGIN = (flag("origin") ?? process.env.WORKTRUST_ORIGIN ?? "https://app.worktrust.io").replace(/\/$/, "");
88
88
  const MCP = flag("url") ?? process.env.WORKTRUST_MCP_URL ?? `${ORIGIN}/api/mcp`;
89
89
  const HOME_DIR = join(homedir(), ".worktrust");
90
90
  const HERE = dirname(fileURLToPath(import.meta.url));
91
- const SCRIPTS = ["setup-mcp.mjs", "log-session.mjs", "count-behaviour.mjs", "transcript-readers.mjs", "session-databases.mjs", "config-edits.mjs", "stretch-evidence.mjs", "chat-exports.mjs", "stack-rules.mjs"];
91
+ const SCRIPTS = ["setup-mcp.mjs", "log-session.mjs", "count-behaviour.mjs", "transcript-readers.mjs", "session-databases.mjs", "config-edits.mjs", "stretch-evidence.mjs", "chat-exports.mjs", "stack-rules.mjs", "runtime-install.mjs", "orchestration-contract.mjs", "orchestration-evidence.mjs", "orchestration-report.mjs"];
92
92
  /** The modules the scripts import by name from beside them; a download keeps that name. */
93
- const IMPORTED = new Set(["transcript-readers.mjs", "session-databases.mjs", "config-edits.mjs", "stretch-evidence.mjs", "chat-exports.mjs", "stack-rules.mjs"]);
93
+ const IMPORTED = new Set(["transcript-readers.mjs", "session-databases.mjs", "config-edits.mjs", "stretch-evidence.mjs", "chat-exports.mjs", "stack-rules.mjs", "runtime-install.mjs", "orchestration-contract.mjs", "orchestration-evidence.mjs", "orchestration-report.mjs"]);
94
94
  const downloaded = (name) => (IMPORTED.has(name) ? name : `${name}.download.mjs`);
95
95
  const BUNDLED = SCRIPTS.every((name) => existsSync(join(HERE, name)));
96
96
  const PLACEHOLDER = `wt_${"0".repeat(43)}`;
@@ -272,13 +272,29 @@ async function pairByCode(host, extra) {
272
272
  * that survives an upgrade), not this process's resolved path, which names one version and breaks
273
273
  * with the next `brew upgrade node`.
274
274
  */
275
- const NODE = (process.env.PATH ?? "").split(OS === "windows" ? ";" : ":").map((dir) => join(dir, OS === "windows" ? "node.exe" : "node")).find((path) => existsSync(path)) ?? process.execPath;
275
+ let NODE = process.env.WORKTRUST_BUNDLED_RUNTIME_DIR ? process.execPath : (process.env.PATH ?? "").split(OS === "windows" ? ";" : ":").map((dir) => join(dir, OS === "windows" ? "node.exe" : "node")).find((path) => existsSync(path)) ?? process.execPath;
276
276
  const KEY_FILE = join(HOME_DIR, "key.json");
277
- const STABLE = join(HOME_DIR, "worktrust.mjs");
277
+ const STABLE_FILE = join(HOME_DIR, "worktrust.mjs");
278
+ let STABLE = STABLE_FILE, runtimePrepared = false;
278
279
  const RENEW_EVERY_MS = 7 * 24 * 3600_000;
279
280
  const KEY_PLACE = "~/.worktrust/key.json (only you can read it)";
280
281
  const ensureHome = () => { mkdirSync(HOME_DIR, { recursive: true, mode: 0o700 }); try { chmodSync(HOME_DIR, 0o700); } catch { /* Windows */ } };
281
282
 
283
+ /** A tool-runner cache is disposable. Install the whole verified runtime/engine before changing wiring. */
284
+ async function prepareBundledRuntime() {
285
+ if (!process.env.WORKTRUST_BUNDLED_RUNTIME_DIR || runtimePrepared) return;
286
+ const { installRuntime } = await import("./runtime-install.mjs");
287
+ if (existsSync(HOME_DIR) && (!lstatSync(HOME_DIR).isDirectory() || lstatSync(HOME_DIR).isSymbolicLink())) fail("the WorkTrust directory must be a directory, not a symlink.");
288
+ ensureHome();
289
+ const installed = installRuntime(process.env.WORKTRUST_BUNDLED_RUNTIME_DIR, HERE, HOME_DIR, ["worktrust.mjs", ...SCRIPTS, "preserve.mjs", "preserve-lines.mjs", "preserve-summary.mjs"]);
290
+ NODE = installed.executable; STABLE = installed.bridge; runtimePrepared = true;
291
+ }
292
+ function saveStableEntry() {
293
+ const temporary = `${STABLE_FILE}.${randomBytes(8).toString("hex")}.tmp`;
294
+ try { writeFileSync(temporary, readFileSync(fileURLToPath(import.meta.url)), { flag: "wx", mode: 0o600 }); renameSync(temporary, STABLE_FILE); }
295
+ finally { try { rmSync(temporary); } catch { /* already renamed */ } }
296
+ }
297
+
282
298
  /**
283
299
  * THE KEY'S PLACE: one file only you can read (mode 600 in a 700 folder), holding the key, its device
284
300
  * private key and when it was last renewed. NO KEYCHAIN (owner, 2026-10-03): a keychain tool can ask
@@ -490,7 +506,7 @@ async function hook() {
490
506
  if (has("hermes") || has("goose")) return sessionEnd();
491
507
  const key = await freshKey();
492
508
  if (!key) process.exit(0);
493
- const child = spawn(process.execPath, [join(HOME_DIR, "log-session.mjs"), ...args.filter((arg) => arg !== "hook")], { stdio: "inherit", env: { ...process.env, WORKTRUST_MCP_URL: key.url, WORKTRUST_MCP_TOKEN: key.token, ...(key.device ? { WORKTRUST_DEVICE_KEY: key.device } : {}) } });
509
+ const child = spawn(process.execPath, [join(BUNDLED ? HERE : HOME_DIR, "log-session.mjs"), ...args.filter((arg) => arg !== "hook")], { stdio: "inherit", env: { ...process.env, WORKTRUST_MCP_URL: key.url, WORKTRUST_MCP_TOKEN: key.token, ...(key.device ? { WORKTRUST_DEVICE_KEY: key.device } : {}) } });
494
510
  child.on("exit", (code) => process.exit(code ?? 0));
495
511
  }
496
512
 
@@ -555,9 +571,10 @@ async function update() {
555
571
  say();
556
572
  if (has("dry-run")) { say(" Dry run: nothing was written and nothing was sent."); return; }
557
573
  if (!(await ask("Continue?"))) { say(" Stopped. Nothing was written."); return; }
558
- ensureHome();
559
574
  const previousVersion = stableVersion();
560
- copyFileSync(fileURLToPath(import.meta.url), STABLE);
575
+ await prepareBundledRuntime();
576
+ ensureHome();
577
+ saveStableEntry();
561
578
  say(` ✓ ${STABLE} is now ${CLI_VERSION}`);
562
579
  // Out first, then in: an app that held a key of its own (a hand-made entry) moves onto the bridge.
563
580
  await run(paths["setup-mcp.mjs"], ["--remove", "--write"], key.token, true);
@@ -610,6 +627,7 @@ async function connect() {
610
627
  say();
611
628
  if (has("dry-run")) { say(" Dry run: nothing was written and nothing was sent."); return; }
612
629
  if (!(await ask("Continue?"))) { say(" Stopped. Nothing was written and nothing was sent."); return; }
630
+ await prepareBundledRuntime();
613
631
 
614
632
  // The device key: made here, its private half kept with the key, its public half bound at WorkTrust.
615
633
  const device = direct ? null : generateKeyPairSync("ed25519");
@@ -628,7 +646,7 @@ async function connect() {
628
646
  keyStore.save({ url: MCP, token, renewedAt: new Date().toISOString(), coupledAt: new Date().toISOString(), identified: true, profile: computerIds().profile_id, account: pairing.account, accountRef: pairing.accountRef, device: device.privateKey.export({ format: "pem", type: "pkcs8" }) });
629
647
  previousNote.erase();
630
648
  ensureHome();
631
- copyFileSync(fileURLToPath(import.meta.url), STABLE);
649
+ saveStableEntry();
632
650
  say(` ✓ Key kept in ${KEY_PLACE}`);
633
651
  }
634
652
  if ((await run(paths["setup-mcp.mjs"], direct ? ["--write"] : ["--write", "--bridge", STABLE], token)).code !== 0) fail("coupling the AI apps failed; the output above says where.");
@@ -692,7 +710,7 @@ async function offerHistory(paths, token, devicePem, url = MCP, rebuild = false)
692
710
  }
693
711
 
694
712
  /** The version stamped in the stable copy in ~/.worktrust, the CLI this computer ran before an update; null without one. */
695
- const stableVersion = () => { try { return /const CLI_VERSION = "([^"]+)";/.exec(readFileSync(STABLE, "utf8"))?.[1] ?? null; } catch { return null; } };
713
+ const stableVersion = () => { try { return /const CLI_VERSION = "([^"]+)";/.exec(readFileSync(STABLE_FILE, "utf8"))?.[1] ?? null; } catch { return null; } };
696
714
 
697
715
  /**
698
716
  * OFFERED ONCE, BY `update`, IN PLAIN WORDS (owner, 2026-10-07): when the computer's earlier lines were made by an earlier CLI
@@ -898,7 +916,8 @@ async function offerCodex() {
898
916
  const viaBridge = existsSync(STABLE);
899
917
  const hookFile = viaBridge ? STABLE : join(HOME_DIR, "log-session.mjs");
900
918
  if (!existsSync(hookFile)) { say(" Couple this computer first: npx worktrust"); return; }
901
- const want = `notify = [${(viaBridge ? [NODE, STABLE, "hook", "--codex-notify"] : [NODE, hookFile, "--codex-notify"]).map((part) => JSON.stringify(part)).join(", ")}]`;
919
+ const desired = () => `notify = [${(viaBridge ? [NODE, STABLE, "hook", "--codex-notify"] : [NODE, hookFile, "--codex-notify"]).map((part) => JSON.stringify(part)).join(", ")}]`;
920
+ let want = desired();
902
921
  const found = codexNotify();
903
922
  say();
904
923
  if (found.text === want) { say(" ✓ Codex already wakes the session hook at the end of every turn."); return; }
@@ -911,6 +930,7 @@ async function offerCodex() {
911
930
  say(` ${found.text ? "↻" : "+"} ${CODEX_CONFIG} → ${want}`);
912
931
  if (has("dry-run")) { say(" Dry run: nothing was written."); return; }
913
932
  if (!has("codex") && !(await ask("Let Codex wake the session hook?", false))) { say(" Not set. npx worktrust update asks again."); return; }
933
+ await prepareBundledRuntime(); want = desired();
914
934
  const rows = [...found.rows];
915
935
  if (found.text) rows.splice(found.at, found.end - found.at + 1, want);
916
936
  else rows.splice(found.insert, 0, ...(found.insert < rows.length && rows[found.insert] !== "" ? [want, ""] : [want]));
@@ -943,7 +963,8 @@ function writeAgyHooks(hooks) {
943
963
  async function offerAntigravity() {
944
964
  if (!antigravityHere()) { if (command === "antigravity") say(" Antigravity is not on this computer (no ~/.gemini/config or ~/.gemini/antigravity*)."); return; }
945
965
  if (!existsSync(STABLE)) { say(" Couple this computer first: npx worktrust"); return; }
946
- const want = { enabled: true, Stop: [{ type: "command", command: `"${NODE}" "${STABLE}" hook --antigravity-stop`, timeout: 10 }] };
966
+ const desired = () => ({ enabled: true, Stop: [{ type: "command", command: `"${NODE}" "${STABLE}" hook --antigravity-stop`, timeout: 10 }] });
967
+ let want = desired();
947
968
  const hooks = agyHooks();
948
969
  say();
949
970
  if (hooks === null) { say(` ${AGY_HOOKS} is not readable JSON, so it is left as it is; Antigravity sessions are still sent whenever another hook runs.`); return; }
@@ -952,6 +973,7 @@ async function offerAntigravity() {
952
973
  say(` ${hooks.worktrust ? "↻" : "+"} ${AGY_HOOKS} → worktrust: Stop runs ${want.Stop[0].command}`);
953
974
  if (has("dry-run")) { say(" Dry run: nothing was written."); return; }
954
975
  if (!has("antigravity") && !(await ask("Let Antigravity wake the session hook?", false))) { say(" Not set. npx worktrust update asks again."); return; }
976
+ await prepareBundledRuntime(); want = desired();
955
977
  writeAgyHooks({ ...hooks, worktrust: want });
956
978
  say(` ✓ Antigravity wakes the session hook. Restart Antigravity to pick it up${existsSync(`${AGY_HOOKS}.worktrust-backup`) ? "; the earlier file is kept as hooks.json.worktrust-backup" : ""}.`);
957
979
  }
@@ -1093,6 +1115,7 @@ function help() {
1093
1115
  say(" days this computer's own sessions lack, reconstructed, never verified hours (asks first)");
1094
1116
  say(" worktrust disconnect take WorkTrust out of every AI app here (asks first)");
1095
1117
  say(" worktrust status what is coupled here");
1118
+ say(" worktrust orchestration report --file recording.jsonl inspect local agent metadata; sends nothing");
1096
1119
  say(" worktrust preserve keep your AI history: the report, then the settings and a local archive, each on your yes");
1097
1120
  say(" --apply keep them: asks per change, backs the file up first (--yes: no question)");
1098
1121
  say(" --archive [dir] a local, metadata-only, hash-chained record of the measured days (~/AI-Evidence)");
@@ -1108,7 +1131,7 @@ function help() {
1108
1131
  // before anything is read or written, --yes included. The hook and the MCP bridge are started by the agent's client
1109
1132
  // itself and stay as they are; `status` only reads.
1110
1133
  const AGENT_ENV = ["CLAUDECODE", "CLAUDE_CODE_ENTRYPOINT", "CODEX_SANDBOX", "CODEX_CI", "GEMINI_CLI", "CURSOR_AGENT", "OPENCODE", "CLINE_ACTIVE", "AIDER_CHAT", "ANTIGRAVITY_AGENT", "WINDSURF_AGENT"];
1111
- const PERSON_ONLY = new Set(["default", "connect", "update", "history", "disconnect", "preserve", "codex", "antigravity", "sources", "web", "import"]);
1134
+ const PERSON_ONLY = new Set(["default", "connect", "update", "history", "disconnect", "preserve", "codex", "antigravity", "sources", "web", "import", "orchestration"]);
1112
1135
  const agentShell = AGENT_ENV.find((name) => process.env[name] && process.env[name] !== "0");
1113
1136
  if (agentShell && PERSON_ONLY.has(command)) {
1114
1137
  say();
@@ -1171,4 +1194,8 @@ else if (command === "antigravity") await offerAntigravity();
1171
1194
  else if (command === "disconnect") await disconnect();
1172
1195
  else if (command === "status") await status();
1173
1196
  else if (command === "preserve") await preserve();
1197
+ else if (command === "orchestration") {
1198
+ if (!["orchestration-report.mjs", "orchestration-evidence.mjs", "orchestration-contract.mjs"].every((name) => existsSync(join(HERE, name)))) fail("Local agent reports need the complete WorkTrust npm/Python package or preservation kit. No file was read or sent.");
1199
+ const { reportFile } = await import("./orchestration-report.mjs"); reportFile(args.slice(1));
1200
+ }
1174
1201
  else help();