@superjackfruitlabs/salaam 0.0.3 → 0.0.4

package/src/station-work.ts

@@ -1,9 +1,11 @@
 import { spawn } from 'node:child_process';
+import type { FileNow, LiveTree } from './station-checkpoints.js';
 import {
   mkdirSync,
   mkdtempSync,
   writeFileSync,
   readFileSync,
+  readdirSync,
   lstatSync,
   rmSync,
   chmodSync,
@@ -33,6 +35,7 @@ import {
   type StationConfig,
 } from './station-config.js';
 import { stationFileResult } from './station-files.js';
+import { type RunGrants, runGrantCovers, runGrantPrefix } from './run-grants.js';
 import { StationSystemd, type StationUnit } from './station-systemd.js';
 
 export interface StationBinding {
@@ -77,17 +80,40 @@ interface UnitRow {
   stop_json: string | null;
 }
 const hashes = /^[a-f0-9]{64}$/;
-class StationFilesDefiniteFailure extends ServiceError {
-  constructor() {
-    super('station_files_changed', 'Protected file primitive refused before mutation');
+export class StationFilesDefiniteFailure extends ServiceError {
+  constructor(code: string) {
+    super(code, 'Protected file primitive refused before mutation');
   }
 }
+/** A helper refusal that provably changed nothing, as the code recorded for it, or null. The
+ * helper writes station_request_invalid as exactly {version, ok, code} and only while decoding,
+ * before it executes anything; any other shape (an effect_state, extra fields) is not definite. */
+export function definiteHelperRefusal(
+  exitCode: number | null,
+  transportFailed: boolean,
+  result: Record<string, unknown>,
+): string | null {
+  if (transportFailed || exitCode !== 1 || result.version !== 1 || result.ok !== false) return null;
+  if (result.code === 'station_files_unavailable' && result.effect_state === 'not_started')
+    return 'station_files_changed';
+  if (
+    result.code === 'station_request_invalid' &&
+    Object.keys(result).sort().join(',') === 'code,ok,version'
+  )
+    return 'station_request_invalid';
+  return null;
+}
 const terminal = (s: string) => ['returned', 'failed', 'outcome_unknown', 'cancelled'].includes(s);
 
 /** Root-only station controller. Writable source access stays behind the private
  * traversal-resistant node primitive; arbitrary checks get a separate OS identity,
  * mount/root/network boundary and bounded, owned systemd cgroup. */
 export class StationWork {
+  /** "Approve for this run" grants and the task each session's run belongs to (service wiring). */
+  grants?: RunGrants;
+  grantScope?: (
+    session: string,
+  ) => { task_id: string; plan_revision: number; task_state: string } | null;
   readonly config: StationConfig;
   readonly configurationDigest: string;
   private readonly directory: string;
@@ -290,10 +316,8 @@ export class StationWork {
         spawned = true;
         try {
           if (id) {
-            const c = this.get(id);
-            if (verificationGuard) verificationGuard();
-            else this.guard(c);
-            if (c.state !== 'dispatching') stationUnavailable();
+            // Own the process first: a guard that refuses below must still leave a pid and identity
+            // that a stop can prove exited (staging card_06a619a3e2e94faf left a pid-less helper).
             const identity = processIdentity(child.pid!);
             if (!identity) stationUnavailable();
             this.store.transaction(() =>
@@ -303,6 +327,10 @@ export class StationWork {
                 )
                 .run(child.pid!, identity, id),
             );
+            const c = this.get(id);
+            if (verificationGuard) verificationGuard();
+            else this.guard(c);
+            if (c.state !== 'dispatching') stationUnavailable();
           }
           child.stdin.end(
             JSON.stringify({
@@ -365,15 +393,8 @@ export class StationWork {
             if (!exited) stationUnavailable();
           }
           const result = object(JSON.parse(Buffer.concat(chunks).toString('utf8')));
-          if (
-            !failed &&
-            code === 1 &&
-            result.version === 1 &&
-            result.ok === false &&
-            result.code === 'station_files_unavailable' &&
-            result.effect_state === 'not_started'
-          )
-            throw new StationFilesDefiniteFailure();
+          const refusal = definiteHelperRefusal(code, failed, result);
+          if (refusal) throw new StationFilesDefiniteFailure(refusal);
           if (failed || code !== 0 || result.version !== 1 || result.ok !== true)
             stationUnavailable();
           accept(
@@ -396,12 +417,43 @@ export class StationWork {
       return (error as NodeJS.ErrnoException).code !== 'ESRCH';
     }
   }
+  /** Whether no process on this host runs the station file helper, proven from every /proc entry. */
+  private noHelperProcess(): boolean {
+    if (process.platform !== 'linux') return false;
+    for (const entry of readdirSync('/proc')) {
+      if (!/^\d+$/.test(entry)) continue;
+      let argv: string[];
+      try {
+        argv = readFileSync(join('/proc', entry, 'cmdline'), 'utf8').split('\0');
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue;
+        return false;
+      }
+      if (argv.includes('salaam-station-files-v1')) return false;
+    }
+    return true;
+  }
   private async stopHelper(id: string): Promise<void> {
     const c = this.get(id);
     if (!c.helper_state || c.helper_state === 'none' || c.helper_state === 'stopped') return;
     this.files.get(id)?.abort();
     try {
-      if (!c.helper_pid || !c.helper_identity) stationUnavailable();
+      if (!c.helper_pid || !c.helper_identity) {
+        // Recorded before the fix above: no pid to prove. Settle only when the whole process table
+        // holds no station helper; any live or unreadable process keeps the call fenced.
+        if (!this.noHelperProcess()) stationUnavailable();
+        this.store.transaction(() =>
+          this.store.db
+            .prepare(
+              "UPDATE station_calls SET helper_state='stopped',helper_stop_json=? WHERE id=?",
+            )
+            .run(
+              canonical({ version: 1, scope: 'host_process_table', method: 'no_helper_process' }),
+              id,
+            ),
+        );
+        return;
+      }
       if (this.processExists(c.helper_pid) || this.processExists(c.helper_pid, true)) {
         if (processIdentity(c.helper_pid) !== c.helper_identity) stationUnavailable();
         process.kill(-c.helper_pid, 'SIGKILL');
@@ -668,7 +720,7 @@ export class StationWork {
       throw new ServiceError('invalid_field', 'Unsupported station mutation');
     const allowed =
       kind === 'patch'
-        ? ['action', 'path', 'expected_tree', 'expected_hash', 'content']
+        ? ['action', 'path', 'expected_tree', 'expected_hash', 'content', 'reason']
         : ['action', 'expected_tree', 'command'];
     if (
       Object.keys(args).some((k) => !allowed.includes(k)) ||
@@ -781,8 +833,298 @@ export class StationWork {
         input_digest: row.input_digest,
       });
     });
+    const prepared = this.get(id);
+    if (kind === 'patch' && prepared.operation_id)
+      this.answerFromGrant(prepared.operation_id, session, args);
     return this.view(id);
   }
+  /** A write the run's grant covers is answered by it, checked again at decision time. The
+   * operation is still prepared, digest-bound and journaled on its own; deletes always ask. */
+  /** An agent's standing "Always allow" rule (pinned at admission or added by a renewal, dropped at the renewal that no
+   * longer lists it) answers a workspace write anywhere in the workspace, never a delete or a
+   * hidden path. Checked again at decision time, so a rule revoked meanwhile answers nothing. */
+  private answerFromRule(operation: string, session: string, args: Record<string, unknown>): void {
+    if (!runGrantCovers('', args)) return;
+    const live = () =>
+      this.authority.approvalRules(session).find((r) => r.scope === 'workspace-write');
+    const rule = live();
+    if (!rule) return;
+    const approval = this.managed.forOperation(operation);
+    if (approval.state !== 'pending') return;
+    this.managed.decide(
+      approval.id,
+      'rule:' + operation,
+      approval.revision,
+      approval.operation_digest,
+      'approve',
+      {
+        decidedBy: 'rule:' + rule.id,
+        receipt: { rule: 'agent-rule', rule_id: rule.id, set_by: rule.set_by },
+        authorize: () => {
+          if (live()?.id !== rule.id)
+            throw new ServiceError(
+              'permission_changed',
+              'The approval rule no longer covers this write',
+            );
+        },
+      },
+    );
+  }
+  private answerFromGrant(operation: string, session: string, args: Record<string, unknown>): void {
+    if (!this.grants || !this.grantScope) return;
+    const binding = this.authority.binding(session) as { run?: { id?: unknown } } | null;
+    const prefix = runGrantPrefix(typeof binding?.run?.id === 'string' ? binding.run.id : '');
+    const live = () => {
+      const scope = this.grantScope!(session);
+      if (!scope || !prefix || !runGrantCovers(prefix, args)) return null;
+      const g = this.grants!.active({
+        session_id: session,
+        binding_digest: digest(binding),
+        ...scope,
+      });
+      return g;
+    };
+    const grant = live();
+    if (!grant) return this.answerFromRule(operation, session, args);
+    const approval = this.managed.forOperation(operation);
+    if (approval.state !== 'pending') return;
+    this.managed.decide(
+      approval.id,
+      'run-grant:' + operation,
+      approval.revision,
+      approval.operation_digest,
+      'approve',
+      {
+        decidedBy: 'run-grant:' + grant.id,
+        receipt: {
+          rule: 'run-grant',
+          grant_id: grant.id,
+          granted_by: grant.granted_by,
+          granted_on: grant.approval_id,
+        },
+        authorize: () => {
+          if (live()?.id !== grant.id)
+            throw new ServiceError(
+              'permission_changed',
+              'The run grant no longer covers this write',
+            );
+        },
+      },
+    );
+  }
+  /** Item 11b: the restore journal. Each write is recorded before it is sent, so a daemon stop
+   * mid-restore leaves an honest unknown, never a silent effect. */
+  private restoreTables(): void {
+    this.store.db.exec(`CREATE TABLE IF NOT EXISTS station_restores(
+      id TEXT PRIMARY KEY NOT NULL, session_id TEXT NOT NULL, request_id TEXT NOT NULL UNIQUE,
+      restore_digest TEXT NOT NULL, approved_by TEXT NOT NULL, state TEXT NOT NULL, receipt TEXT);
+    CREATE TABLE IF NOT EXISTS station_restore_writes(
+      restore_id TEXT NOT NULL REFERENCES station_restores(id), n INTEGER NOT NULL, path TEXT NOT NULL,
+      args_json TEXT NOT NULL, state TEXT NOT NULL, result_json TEXT, artifact_id TEXT,
+      PRIMARY KEY(restore_id, n));`);
+  }
+  /** Item 11b: the live workspace through the helper's closed verbs (inspect, search, read). A
+   * path is absent only when an exact search finds no entry for it; a file the helper refuses to
+   * read (too large, not text) is unreadable, never guessed. */
+  async live(): Promise<LiveTree> {
+    const inspected = await this.helper({ action: 'inspect' });
+    return {
+      tree: String(inspected.tree_digest),
+      file: async (path: string): Promise<FileNow> => {
+        let offset: number | null = 0,
+          found = false;
+        while (offset !== null && !found) {
+          const page: Record<string, any> = await this.helper({
+            action: 'search',
+            query: path,
+            offset,
+          });
+          found = (page.entries as { path: string }[]).some((e) => e.path === path);
+          offset = page.next_offset ?? null;
+        }
+        if (!found) return { state: 'absent' };
+        try {
+          const read = await this.helper({ action: 'read', path });
+          return { state: 'content', content: String(read.content), sha256: String(read.sha256) };
+        } catch {
+          return { state: 'unreadable' };
+        }
+      },
+    };
+  }
+  /** Item 11b: the journal's answer for a restore request already seen, or null for a new one.
+   * A replay returns the saved receipt exactly; the same request for another restore is a
+   * conflict; an unfinished one says so. Checked before any plan is recomputed. */
+  replayed(session: string, request: string, restoreDigest: string): unknown | null {
+    this.restoreTables();
+    const saved = this.store.db
+      .prepare('SELECT * FROM station_restores WHERE request_id=?')
+      .get(request);
+    if (!saved) return null;
+    if (saved.restore_digest !== restoreDigest || saved.session_id !== session)
+      throw new ServiceError(
+        'request_conflict',
+        'This restore request was used for another restore',
+      );
+    if (saved.receipt) return JSON.parse(String(saved.receipt));
+    throw new ServiceError('restore_unconfirmed', 'This restore did not finish; review it again');
+  }
+  /** At start: a restore write that was in flight has an unknown outcome; its restore is partial. */
+  recoverRestores(): void {
+    this.restoreTables();
+    this.store.transaction(() => {
+      for (const w of this.store.db
+        .prepare("SELECT restore_id,n FROM station_restore_writes WHERE state='dispatching'")
+        .all()) {
+        this.store.db
+          .prepare(
+            "UPDATE station_restore_writes SET state='outcome_unknown' WHERE restore_id=? AND n=?",
+          )
+          .run(String(w.restore_id), Number(w.n));
+        this.store.db
+          .prepare("UPDATE station_restores SET state='partial' WHERE id=?")
+          .run(String(w.restore_id));
+      }
+    });
+  }
+  /**
+   * Item 11b: restore files exactly as planned and approved, after the run has ended. The caller
+   * checks the ended run and the approval; this writes. It refuses a workspace whose live tree is
+   * not the reviewed one, then sends each write through the protected helper in order, chaining
+   * the expected tree and each file's current hash, with a receipt per file. The same request
+   * replays its receipt. A failure stops the restore; nothing is retried.
+   */
+  async restore(
+    session: string,
+    rootDigest: string,
+    plan: {
+      restore_digest: string;
+      current_tree: string;
+      writes: { path: string; content: string | null; expected_hash: string | null }[];
+    },
+    request: string,
+    approvedBy: string,
+  ): Promise<unknown> {
+    this.restoreTables();
+    const saved = this.store.db
+      .prepare('SELECT * FROM station_restores WHERE request_id=?')
+      .get(request);
+    if (saved) {
+      if (saved.restore_digest !== plan.restore_digest || saved.session_id !== session)
+        throw new ServiceError(
+          'request_conflict',
+          'This restore request was used for another restore',
+        );
+      if (saved.receipt) return JSON.parse(String(saved.receipt));
+      throw new ServiceError('restore_unconfirmed', 'This restore did not finish; review it again');
+    }
+    const live = (await this.helper({ action: 'inspect' })) as { tree_digest?: unknown };
+    if (live.tree_digest !== plan.current_tree)
+      throw new ServiceError(
+        'restore_changed',
+        'The workspace changed since this restore was reviewed',
+      );
+    const id = randomUUID();
+    this.store.transaction(() =>
+      this.store.db
+        .prepare("INSERT INTO station_restores VALUES (?,?,?,?,?,'running',NULL)")
+        .run(id, session, request, plan.restore_digest, approvedBy),
+    );
+    let tree = plan.current_tree;
+    const done: { path: string; artifact_id: string }[] = [];
+    let stopped: string | null = null;
+    for (const [n, w] of plan.writes.entries()) {
+      const args = {
+        action: 'patch',
+        path: w.path,
+        expected_tree: tree,
+        expected_hash: w.expected_hash,
+        content: w.content,
+        // The helper accepts only a 64-hex request id: one per restore write, stable on replay.
+        request_id: digest({ restore: id, write: n }),
+        deadline_ms: Date.now() + 5000,
+      };
+      this.store.transaction(() =>
+        this.store.db
+          .prepare("INSERT INTO station_restore_writes VALUES (?,?,?,?,'dispatching',NULL,NULL)")
+          .run(id, n, w.path, canonical(args)),
+      );
+      let result: Record<string, unknown>;
+      try {
+        result = (await this.helper(args)) as Record<string, unknown>;
+      } catch (error) {
+        const definite = error instanceof StationFilesDefiniteFailure;
+        this.store.transaction(() =>
+          this.store.db
+            .prepare(
+              'UPDATE station_restore_writes SET state=?,result_json=? WHERE restore_id=? AND n=?',
+            )
+            .run(
+              definite ? 'failed' : 'outcome_unknown',
+              canonical({
+                code: definite ? (error as ServiceError).code : 'station_execution_unconfirmed',
+              }),
+              id,
+              n,
+            ),
+        );
+        stopped = w.path;
+        break;
+      }
+      const artifact = this.artifacts.prepare(
+        session,
+        canonical({
+          version: 1,
+          kind: 'station-restore-receipt',
+          restore_id: id,
+          request_id: request,
+          restore_digest: plan.restore_digest,
+          approved_by: approvedBy,
+          session_id: session,
+          root_digest: rootDigest,
+          configuration_digest: this.configurationDigest,
+          path: w.path,
+          patch: {
+            content: w.content,
+            expected_tree: args.expected_tree,
+            expected_hash: w.expected_hash,
+          },
+          result,
+        }),
+      );
+      this.store.transaction(() => {
+        artifact.commit();
+        this.store.db
+          .prepare(
+            "UPDATE station_restore_writes SET state='returned',result_json=?,artifact_id=? WHERE restore_id=? AND n=?",
+          )
+          .run(canonical(result), artifact.id, id, n);
+      });
+      done.push({ path: w.path, artifact_id: artifact.id });
+      tree = String(result.tree_digest);
+    }
+    const receipt = {
+      version: 1 as const,
+      state: stopped ? ('partial' as const) : ('restored' as const),
+      restore_id: id,
+      restore_digest: plan.restore_digest,
+      tree_digest: tree,
+      writes: done,
+      ...(stopped ? { stopped_at: stopped } : {}),
+    };
+    this.store.transaction(() => {
+      this.store.db
+        .prepare('UPDATE station_restores SET state=?,receipt=? WHERE id=?')
+        .run(receipt.state, canonical(receipt), id);
+      this.store.event(session, 'station.restored', {
+        restore_id: id,
+        restore_digest: plan.restore_digest,
+        approved_by: approvedBy,
+        state: receipt.state,
+      });
+    });
+    return receipt;
+  }
   run(id: string): unknown {
     const c = this.get(id);
     if (terminal(c.state) || this.jobs.has(id)) return this.view(id);
@@ -811,7 +1153,7 @@ export class StationWork {
             this.change(
               current,
               current.kind === 'patch' && !definite ? 'outcome_unknown' : 'failed',
-              { code: definite ? 'station_files_changed' : 'station_execution_unconfirmed' },
+              { code: definite ? error.code : 'station_execution_unconfirmed' },
             );
             if (current.operation_id) {
               if (definite)
@@ -843,7 +1185,13 @@ export class StationWork {
     if (c.kind === 'patch') {
       const result = await this.helper(
         {
-          ...args,
+          // Only the helper's own fields: it refuses any field it does not know (the agent's
+          // reason is for the approval detail and stays in the operation's arguments).
+          action: args.action,
+          path: args.path,
+          expected_tree: args.expected_tree,
+          expected_hash: args.expected_hash,
+          content: args.content,
           request_id: id,
           deadline_ms: Date.now() + this.authority.leaseWindow(c.session_id, c.root_digest, 5000),
         },
@@ -1067,6 +1415,7 @@ export class StationWork {
   }
   async initialize(): Promise<void> {
     this.proven = false;
+    this.recoverRestores();
     for (const row of this.store.db
       .prepare(
         "SELECT id FROM station_calls WHERE helper_state NOT IN ('none','stopped') ORDER BY rowid",

package/src/store.ts

@@ -49,6 +49,8 @@ export class Store {
     after: import('./workspaces.js').WorkspaceTree,
   ) => void;
   taskGrantCheck?: (session: string) => void;
+  /** Provenance: the OS identity that local tool effects run as. */
+  toolExecution?: { mode: string; user: string; uid: number };
   jobGrantCheck?: (session: string) => void;
   taskModelAdmission?: (
     session: string,
@@ -57,11 +59,15 @@ export class Store {
     output: number,
   ) => void;
   taskBudgetDenied?: (session: string, error: unknown) => void;
+  /** A durable task's own attempts are bounded by the task's request limit, not the attempt default. */
+  taskAttemptRequestLimit?: (session: string) => number | undefined;
   taskChildReserve?: (session: string, attempt: string, count: number) => void;
   taskChildFinished?: (attempt: string) => void;
   taskCommandAdmission?: (session: string) => void;
   taskRemainingRuntime?: (session: string) => number;
   private committed: DurableEvent[] | null = null;
+  private readonly activity = new Map<string, number>();
+  readonly openedAt = Date.now();
   constructor(path: string) {
     this.db = new DatabaseSync(path);
     if (path !== ':memory:') chmodSync(path, 0o600);
@@ -418,6 +424,8 @@ export class Store {
     } finally {
       this.committed = null;
     }
+    const now = Date.now();
+    for (const event of events!) this.activity.set(event.session_id, now);
     for (const event of events!) this.changes.emit('event', event);
     return result!;
   }
@@ -514,6 +522,7 @@ export class Store {
                   local_workspace: true,
                   local_coding: local.coding === true,
                   output_cap: local.outputCap ?? true,
+                  ...(this.toolExecution ? { tool_execution: this.toolExecution } : {}),
                 }
               : {}),
           },
@@ -598,6 +607,7 @@ export class Store {
           local_workspace: true,
           local_coding: this.localCoding(id),
           output_cap: this.localOutputCap(id) ?? true,
+          ...(this.toolExecution ? { tool_execution: this.toolExecution } : {}),
           forked_from: id,
         },
         request,
@@ -637,6 +647,14 @@ export class Store {
       return { name };
     });
   }
+  /** Wall-clock time of the last committed event for a session in this process, if any. */
+  lastActivity(id: string): number | null {
+    return this.activity.get(id) ?? null;
+  }
+  /** The newest committed event in this process, or the time the store opened. */
+  lastActivityAny(): number {
+    return Math.max(this.openedAt, ...this.activity.values());
+  }
   sessions(): Session[] {
     return (
       this.db.prepare('SELECT id FROM sessions ORDER BY rowid').all() as { id: string }[]