blun-king-cli 9.1.567 → 9.1.569

package/agent-spine-plugin/src/lib/selfstarter-jobs.js

@@ -0,0 +1,149 @@
+import {
+  ACTIONS, HOSTS, appendReceipt, blocker, capabilities, currentTaskValid, emptyJobs, emptyPolicy,
+  exactGrant, executionPolicyFindingsInternal, integer, leaseExpired, lockedStates, normalizeJobs,
+  normalizePolicy, pathsFor, preserveJob, readJson, receiptDigest, referenceState,
+  requireOwnerConfirmation, resultHash, safeText, selfstarterFindingsInternal, stableId, timestamp,
+  validateGrantReferences, withLock
+} from "./selfstarter-core.js";
+import { workspaceFingerprint } from "./selfstarter-workspace.js";
+
+export async function resolveSessionJob({
+  root = process.cwd(), actorId = null, projectId = null, groupId = null, taskId = null,
+  host, sessionId, action = "effect", now = new Date()
+}) {
+  if (!ACTIONS.has(action)) throw new Error("session job resolution requires start, resume, or effect");
+  if (!HOSTS.has(host)) throw new Error("self-starter host must be claude or codex");
+  const session = stableId(sessionId, "sessionId");
+  const at = timestamp(now, "now");
+  const paths = await pathsFor(root);
+  const [policy, state] = await Promise.all([
+    readJson(paths.executionPolicyPath, paths.catalog.root, normalizePolicy, emptyPolicy),
+    readJson(paths.selfstarterPath, paths.catalog.root, normalizeJobs, emptyJobs)
+  ]);
+  const { graph, coordination } = await referenceState(paths.catalog);
+  const findings = [
+    ...executionPolicyFindingsInternal(policy, graph, coordination, { checkCurrentReferences: false }),
+    ...selfstarterFindingsInternal(state, policy, graph, coordination)
+  ];
+  if (findings.length) throw new Error(`self-starter failed closed: ${findings.join(", ")}`);
+  const candidates = state.jobs.filter((job) => job.lease?.sessionId === session);
+  if (!candidates.length) return null;
+  if (candidates.length !== 1) throw new Error("host session has multiple self-starter leases");
+  const job = candidates[0];
+  if (leaseExpired(job, at)) throw new Error(`job ${job.id} lease expired`);
+  for (const [value, expected, label] of [
+    [actorId, job.actorId, "actor"], [projectId, job.projectId, "project"],
+    [taskId, job.taskId, "task"], [groupId, job.groupId, "group"], [host, job.host, "host"]
+  ]) {
+    if (value !== null && value !== undefined && value !== expected) throw new Error(`self-starter ${label} scope mismatch for ${job.id}`);
+  }
+  exactGrant(policy, job, action, at);
+  if (!currentTaskValid(job, coordination)) throw new Error("self-starter task or assignment changed");
+  return {
+    jobId: job.id, actorId: job.actorId, projectId: job.projectId, groupId: job.groupId,
+    taskId: job.taskId, host: job.host, sessionId: session
+  };
+}
+
+export async function registerJob({
+  root = process.cwd(), id, grantId, maxRetries = 3, leaseSeconds = 120,
+  baseRetrySeconds = 5, confirmation, now = new Date()
+}) {
+  requireOwnerConfirmation(confirmation);
+  const jobId = stableId(id, "jobId");
+  const at = timestamp(now, "now");
+  const paths = await pathsFor(root);
+  const fingerprint = await workspaceFingerprint(paths.catalog.root);
+  const { graph, coordination } = await referenceState(paths.catalog);
+  return withLock(paths.executionPolicyPath, () => readJson(paths.executionPolicyPath, paths.catalog.root, normalizePolicy, emptyPolicy), (policy) => withLock(
+    paths.selfstarterPath,
+    () => readJson(paths.selfstarterPath, paths.catalog.root, normalizeJobs, emptyJobs),
+    (state) => {
+      const policyIssues = executionPolicyFindingsInternal(policy, graph, coordination);
+      const stateIssues = selfstarterFindingsInternal(state, policy, graph, coordination);
+      if (policyIssues.length || stateIssues.length) throw new Error(`self-starter registration failed closed: ${[...policyIssues, ...stateIssues].join(", ")}`);
+      const grant = policy.grants.find((item) => item.id === grantId && item.jobId === jobId);
+      if (!grant) throw new Error("registration requires the exact current execution grant");
+      if (state.jobs.some((job) => job.id === jobId)) throw new Error("job IDs are immutable");
+      const template = {
+        id: jobId, taskId: grant.taskId, actorId: grant.actorId, targetId: grant.targetId,
+        projectId: grant.projectId, groupId: grant.groupId, host: grant.host,
+        capabilities: [...grant.capabilities], grantId: grant.id
+      };
+      exactGrant(policy, template, "start", at);
+      if (!validateGrantReferences(grant, graph, coordination)) throw new Error("execution grant no longer matches the current task");
+      const job = {
+        ...template, status: "waiting",
+        checkpoint: {
+          sequence: 0, workspaceDigest: fingerprint.digest, workspaceFiles: fingerprint.files,
+          workspaceBytes: fingerprint.bytes, lastToolUseId: null, resultDigest: null,
+          retryCount: 0, nextRetryAt: null, updatedAt: at
+        },
+        lease: null, pendingEffect: null,
+        maxRetries: integer(maxRetries, "maxRetries", 0, 10),
+        leaseSeconds: integer(leaseSeconds, "leaseSeconds", 15, 900),
+        baseRetrySeconds: integer(baseRetrySeconds, "baseRetrySeconds", 1, 3600),
+        lastBlocker: null, createdAt: at, updatedAt: at, authority: "execution-state-only"
+      };
+      state.jobs.push(job);
+      state.jobs.sort((a, b) => a.id.localeCompare(b.id));
+      appendReceipt(state, job, `receipt:registered:${receiptDigest({ id: job.id, at }).slice(0, 20)}`, "registered", at, { checkpoint: job.checkpoint.workspaceDigest });
+      return { job, selfstarterPath: paths.selfstarterPath, executionPolicyPath: paths.executionPolicyPath };
+    }
+  ), false);
+}
+
+export async function cancelJob({ root = process.cwd(), id, reason, confirmation, now = new Date() }) {
+  requireOwnerConfirmation(confirmation);
+  stableId(id, "jobId");
+  const at = timestamp(now, "now");
+  const cancelReason = safeText(reason, "reason", 500);
+  return lockedStates(root, ({ state, paths }) => {
+    const job = state.jobs.find((item) => item.id === id);
+    if (!job) throw new Error("unknown self-starter job");
+    if (["completed", "cancelled"].includes(job.status)) throw new Error("self-starter job is already terminal");
+    preserveJob(state, job, "cancelled", at);
+    job.status = "cancelled";
+    job.lease = null;
+    job.pendingEffect = null;
+    job.lastBlocker = { code: "owner-cancelled", at, authority: "execution-state-only" };
+    job.cancelReason = cancelReason;
+    job.updatedAt = at;
+    appendReceipt(state, job, `receipt:cancel:${receiptDigest({ id, at }).slice(0, 20)}`, "cancelled", at, { reasonDigest: resultHash(cancelReason) });
+    return { job, selfstarterPath: paths.selfstarterPath };
+  });
+}
+
+export async function deleteJob({ root = process.cwd(), id, confirmation }) {
+  requireOwnerConfirmation(confirmation);
+  stableId(id, "jobId");
+  return lockedStates(root, ({ state, paths }) => {
+    const job = state.jobs.find((item) => item.id === id);
+    if (job?.lease || job?.pendingEffect) throw new Error("cannot delete a leased or uncheckpointed job");
+    const existed = Boolean(job);
+    state.jobs = state.jobs.filter((item) => item.id !== id);
+    state.history = state.history.filter((entry) => entry.recordId !== id && entry.value?.id !== id);
+    state.receipts = state.receipts.filter((receipt) => receipt.jobId !== id);
+    return { deleted: existed, id, selfstarterPath: paths.selfstarterPath };
+  });
+}
+
+export async function selfstarterContext({ root = process.cwd(), actorId = null, projectId = null, taskId = null, includeTerminal = false } = {}) {
+  const paths = await pathsFor(root);
+  const [policy, state] = await Promise.all([
+    readJson(paths.executionPolicyPath, paths.catalog.root, normalizePolicy, emptyPolicy),
+    readJson(paths.selfstarterPath, paths.catalog.root, normalizeJobs, emptyJobs)
+  ]);
+  const { graph, coordination } = await referenceState(paths.catalog);
+  const findings = [...executionPolicyFindingsInternal(policy, graph, coordination), ...selfstarterFindingsInternal(state, policy, graph, coordination)];
+  if (findings.length) throw new Error(`self-starter failed closed: ${findings.join(", ")}`);
+  const items = state.jobs.filter((job) => (!actorId || job.actorId === actorId) && (!projectId || job.projectId === projectId)
+    && (!taskId || job.taskId === taskId) && (includeTerminal || !["completed", "cancelled"].includes(job.status)))
+    .map((job) => ({
+      id: job.id, taskId: job.taskId, actorId: job.actorId, targetId: job.targetId,
+      projectId: job.projectId, groupId: job.groupId, host: job.host, status: job.status,
+      checkpoint: { ...job.checkpoint }, leased: Boolean(job.lease), pendingEffect: Boolean(job.pendingEffect),
+      lastBlocker: job.lastBlocker, updatedAt: job.updatedAt, authority: "execution-state-only"
+    }));
+  return { schema: "agentspine.selfstarter-context/v1", root: paths.catalog.root, items, authority: "execution-state-only" };
+}

package/agent-spine-plugin/src/lib/selfstarter-lease.js

@@ -0,0 +1,204 @@
+import {
+  HOSTS, appendReceipt, blocker, currentTaskValid, ensureScope, exactGrant, leaseExpired,
+  lockedStates, preserveJob, receiptDigest, resultHash, stableId, timestamp
+} from "./selfstarter-core.js";
+import { incompleteWorkspaceScan, workspaceFingerprint } from "./selfstarter-workspace.js";
+
+export async function startOrResumeJob({ root = process.cwd(), actorId, projectId, groupId = null, taskId = null, jobId = null, host, sessionId, now = new Date() }) {
+  const scope = {
+    actorId: stableId(actorId, "actorId"), projectId: stableId(projectId, "projectId"),
+    groupId: stableId(groupId, "groupId", true), taskId: stableId(taskId, "taskId", true),
+    jobId: stableId(jobId, "jobId", true), host, sessionId: stableId(sessionId, "sessionId")
+  };
+  if (!HOSTS.has(host)) throw new Error("self-starter host must be claude or codex");
+  const at = timestamp(now, "now");
+  const fingerprint = await workspaceFingerprint(root);
+  return lockedStates(root, ({ policy, state, coordination, paths }) => {
+    const candidates = state.jobs.filter((job) => !["completed", "cancelled", "exhausted"].includes(job.status)
+      && job.actorId === scope.actorId && job.projectId === scope.projectId && job.groupId === scope.groupId
+      && job.host === host && (!scope.taskId || job.taskId === scope.taskId) && (!scope.jobId || job.id === scope.jobId));
+    if (!candidates.length) return { job: null, reason: "no-exact-waiting-job", selfstarterPath: paths.selfstarterPath };
+    if (candidates.length !== 1) throw new Error("multiple eligible self-starter jobs require an exact job or task scope");
+    const job = candidates[0];
+    ensureScope(job, scope);
+    if (!currentTaskValid(job, coordination)) {
+      preserveJob(state, job, "task-invalid", at);
+      blocker(job, "task-or-assignment-changed", at);
+      appendReceipt(state, job, `receipt:blocked:${receiptDigest({ id: job.id, at, code: job.lastBlocker.code }).slice(0, 20)}`, "blocked", at, { code: job.lastBlocker.code });
+      return { job: null, blocked: true, reason: job.lastBlocker.code, selfstarterPath: paths.selfstarterPath };
+    }
+    if (job.lease && !leaseExpired(job, at) && job.lease.sessionId !== scope.sessionId) {
+      throw new Error(`job ${job.id} has an active lease`);
+    }
+    const hasPriorRun = Boolean(job.lease) || state.receipts.some((receipt) => receipt.jobId === job.id && ["start", "resume"].includes(receipt.event));
+    const action = job.checkpoint.sequence === 0 && !hasPriorRun ? "start" : "resume";
+    exactGrant(policy, job, action, at);
+    if (job.checkpoint.nextRetryAt && new Date(job.checkpoint.nextRetryAt) > new Date(at)) {
+      return { job: null, blocked: true, reason: "retry-backoff-active", nextRetryAt: job.checkpoint.nextRetryAt, selfstarterPath: paths.selfstarterPath };
+    }
+    if (job.status === "blocked" && job.lastBlocker?.code === "host-reported-blocker") {
+      return { job: null, blocked: true, reason: "host-reported-blocker", selfstarterPath: paths.selfstarterPath };
+    }
+    if (job.pendingEffect && leaseExpired(job, at)) {
+      if (fingerprint.digest !== job.pendingEffect.beforeDigest) {
+        preserveJob(state, job, "crash-workspace-unknown", at);
+        blocker(job, "workspace-changed-after-uncheckpointed-effect", at);
+        appendReceipt(state, job, `receipt:blocked:${receiptDigest({ id: job.id, at, code: job.lastBlocker.code }).slice(0, 20)}`, "blocked", at, { code: job.lastBlocker.code });
+        return { job: null, blocked: true, reason: job.lastBlocker.code, selfstarterPath: paths.selfstarterPath };
+      }
+      preserveJob(state, job, "crash-recovered", at);
+      job.pendingEffect = null;
+      job.checkpoint.retryCount += 1;
+      if (job.checkpoint.retryCount > job.maxRetries) {
+        blocker(job, "retry-budget-exhausted", at);
+        return { job: null, blocked: true, reason: job.lastBlocker.code, selfstarterPath: paths.selfstarterPath };
+      }
+    }
+    if (fingerprint.digest !== job.checkpoint.workspaceDigest) {
+      preserveJob(state, job, "workspace-drift", at);
+      blocker(job, "workspace-changed-outside-checkpoint", at);
+      appendReceipt(state, job, `receipt:blocked:${receiptDigest({ id: job.id, at, code: job.lastBlocker.code }).slice(0, 20)}`, "blocked", at, { code: job.lastBlocker.code });
+      return { job: null, blocked: true, reason: job.lastBlocker.code, selfstarterPath: paths.selfstarterPath };
+    }
+    const receiptId = `receipt:${action}:${receiptDigest({ job: job.id, session: scope.sessionId }).slice(0, 20)}`;
+    const existing = state.receipts.find((receipt) => receipt.id === receiptId);
+    if (existing && job.lease?.sessionId === scope.sessionId) return { job, action, duplicate: true, receipt: existing, selfstarterPath: paths.selfstarterPath };
+    if (existing) return {
+      job: null, action, duplicate: true, blocked: true, reason: "session-lifecycle-already-closed",
+      receipt: existing, selfstarterPath: paths.selfstarterPath
+    };
+    preserveJob(state, job, action, at);
+    job.status = "running";
+    job.lastBlocker = null;
+    job.lease = {
+      sessionId: scope.sessionId, host, acquiredAt: at,
+      expiresAt: new Date(new Date(at).getTime() + job.leaseSeconds * 1000).toISOString(),
+      workspaceDigest: fingerprint.digest
+    };
+    job.updatedAt = at;
+    const { receipt } = appendReceipt(state, job, receiptId, action, at, { sessionId: scope.sessionId, workspaceDigest: fingerprint.digest });
+    return { job, action, duplicate: false, receipt, selfstarterPath: paths.selfstarterPath, authority: "explicit-local-execution-policy" };
+  });
+}
+
+export async function authorizeJobEffect({
+  root = process.cwd(), jobId, actorId, projectId, groupId = null, taskId,
+  host, sessionId, toolName, toolUseId, now = new Date()
+}) {
+  const scope = {
+    jobId: stableId(jobId, "jobId"), actorId: stableId(actorId, "actorId"),
+    projectId: stableId(projectId, "projectId"), groupId: stableId(groupId, "groupId", true),
+    taskId: stableId(taskId, "taskId"), host, sessionId: stableId(sessionId, "sessionId")
+  };
+  const capability = `tool:${stableId(toolName, "toolName")}`;
+  const deliveryId = stableId(toolUseId, "toolUseId");
+  const at = timestamp(now, "now");
+  const fingerprint = await workspaceFingerprint(root);
+  if (fingerprint.skipped.length) throw incompleteWorkspaceScan(fingerprint.skipped);
+  return lockedStates(root, ({ policy, state, coordination, paths }) => {
+    const job = state.jobs.find((item) => item.id === scope.jobId);
+    if (!job) throw new Error("unknown self-starter job");
+    ensureScope(job, scope);
+    exactGrant(policy, job, "effect", at);
+    if (!currentTaskValid(job, coordination)) throw new Error("self-starter task or assignment changed");
+    if (job.status !== "running" || !job.lease || leaseExpired(job, at) || job.lease.sessionId !== scope.sessionId) throw new Error("self-starter effect requires the current live lease");
+    if (!job.capabilities.includes(capability)) throw new Error(`default deny: capability ${capability} is not granted for ${job.id}`);
+    if (fingerprint.digest !== job.checkpoint.workspaceDigest || fingerprint.digest !== job.lease.workspaceDigest) throw new Error("workspace changed outside the current checkpoint");
+    if (job.pendingEffect) {
+      if (job.pendingEffect.toolUseId === deliveryId && job.pendingEffect.capability === capability) return { allowed: true, duplicate: true, job, pendingEffect: job.pendingEffect };
+      throw new Error("another self-starter effect is already pending");
+    }
+    preserveJob(state, job, "effect-authorized", at);
+    job.pendingEffect = { toolUseId: deliveryId, capability, beforeDigest: fingerprint.digest, authorizedAt: at, sessionId: scope.sessionId };
+    job.updatedAt = at;
+    const receiptId = `receipt:authorize:${receiptDigest({ job: job.id, toolUseId: deliveryId, capability }).slice(0, 20)}`;
+    const { receipt } = appendReceipt(state, job, receiptId, "effect-authorized", at, { toolUseId: deliveryId, capability, beforeDigest: fingerprint.digest });
+    return { allowed: true, duplicate: false, job, pendingEffect: job.pendingEffect, receipt, selfstarterPath: paths.selfstarterPath };
+  });
+}
+
+export async function checkpointJobEffect({
+  root = process.cwd(), jobId, actorId, projectId, groupId = null, taskId,
+  host, sessionId, toolName, toolUseId, success = true, result = null, now = new Date()
+}) {
+  const scope = {
+    jobId: stableId(jobId, "jobId"), actorId: stableId(actorId, "actorId"),
+    projectId: stableId(projectId, "projectId"), groupId: stableId(groupId, "groupId", true),
+    taskId: stableId(taskId, "taskId"), host, sessionId: stableId(sessionId, "sessionId")
+  };
+  const capability = `tool:${stableId(toolName, "toolName")}`;
+  const deliveryId = stableId(toolUseId, "toolUseId");
+  const at = timestamp(now, "now");
+  const fingerprint = await workspaceFingerprint(root);
+  return lockedStates(root, ({ policy, state, coordination, paths }) => {
+    const job = state.jobs.find((item) => item.id === scope.jobId);
+    if (!job) throw new Error("unknown self-starter job");
+    ensureScope(job, scope);
+    exactGrant(policy, job, "effect", at);
+    if (!currentTaskValid(job, coordination)) throw new Error("self-starter task or assignment changed");
+    const receiptId = `receipt:checkpoint:${receiptDigest({ job: job.id, toolUseId: deliveryId }).slice(0, 20)}`;
+    const existing = state.receipts.find((receipt) => receipt.id === receiptId);
+    if (existing && job.checkpoint.lastToolUseId === deliveryId) return { job, duplicate: true, receipt: existing, selfstarterPath: paths.selfstarterPath };
+    if (!job.lease || job.lease.sessionId !== scope.sessionId || !job.pendingEffect
+      || job.pendingEffect.toolUseId !== deliveryId || job.pendingEffect.capability !== capability) throw new Error("effect checkpoint does not match the pending authorization");
+    preserveJob(state, job, success ? "effect-succeeded" : "effect-failed", at);
+    job.checkpoint.sequence += 1;
+    job.checkpoint.workspaceDigest = fingerprint.digest;
+    job.checkpoint.workspaceFiles = fingerprint.files;
+    job.checkpoint.workspaceBytes = fingerprint.bytes;
+    job.checkpoint.lastToolUseId = deliveryId;
+    job.checkpoint.resultDigest = resultHash(result);
+    job.checkpoint.updatedAt = at;
+    if (success) {
+      job.checkpoint.retryCount = 0;
+      job.checkpoint.nextRetryAt = null;
+      job.lastBlocker = null;
+      job.lease.workspaceDigest = fingerprint.digest;
+      job.lease.expiresAt = new Date(new Date(at).getTime() + job.leaseSeconds * 1000).toISOString();
+    } else {
+      job.checkpoint.retryCount += 1;
+      if (job.checkpoint.retryCount > job.maxRetries) blocker(job, "retry-budget-exhausted", at);
+      else {
+        const seconds = Math.min(3600, job.baseRetrySeconds * (2 ** (job.checkpoint.retryCount - 1)));
+        job.checkpoint.nextRetryAt = new Date(new Date(at).getTime() + seconds * 1000).toISOString();
+        blocker(job, "effect-failed", at);
+      }
+    }
+    job.pendingEffect = null;
+    job.updatedAt = at;
+    const { receipt } = appendReceipt(state, job, receiptId, success ? "effect-succeeded" : "effect-failed", at, {
+      toolUseId: deliveryId, capability, checkpointSequence: job.checkpoint.sequence,
+      workspaceDigest: fingerprint.digest, resultDigest: job.checkpoint.resultDigest, retryCount: job.checkpoint.retryCount
+    });
+    return { job, duplicate: false, receipt, selfstarterPath: paths.selfstarterPath };
+  });
+}
+
+export async function closeJobLease({ root = process.cwd(), jobId, actorId, projectId, groupId = null, taskId, host, sessionId, status = "waiting", now = new Date() }) {
+  if (!["waiting", "blocked", "completed"].includes(status)) throw new Error("closing status must be waiting, blocked, or completed");
+  const scope = {
+    jobId: stableId(jobId, "jobId"), actorId: stableId(actorId, "actorId"),
+    projectId: stableId(projectId, "projectId"), groupId: stableId(groupId, "groupId", true),
+    taskId: stableId(taskId, "taskId"), host, sessionId: stableId(sessionId, "sessionId")
+  };
+  const at = timestamp(now, "now");
+  return lockedStates(root, ({ policy, state, coordination, paths }) => {
+    const job = state.jobs.find((item) => item.id === scope.jobId);
+    if (!job) throw new Error("unknown self-starter job");
+    ensureScope(job, scope);
+    exactGrant(policy, job, "resume", at);
+    if (!currentTaskValid(job, coordination) && status !== "completed") throw new Error("self-starter task or assignment changed");
+    const receiptId = `receipt:close:${receiptDigest({ job: job.id, session: scope.sessionId, status }).slice(0, 20)}`;
+    const existing = state.receipts.find((receipt) => receipt.id === receiptId);
+    if (existing && !job.lease) return { job, duplicate: true, receipt: existing, selfstarterPath: paths.selfstarterPath };
+    if (!job.lease || job.lease.sessionId !== scope.sessionId) throw new Error("only the current lease holder may close a job");
+    if (job.pendingEffect) throw new Error("cannot close a job with an uncheckpointed effect");
+    preserveJob(state, job, "lease-closed", at);
+    job.status = status;
+    job.lease = null;
+    if (status === "blocked") job.lastBlocker = { code: "host-reported-blocker", at, authority: "execution-state-only" };
+    job.updatedAt = at;
+    const { receipt } = appendReceipt(state, job, receiptId, "lease-closed", at, { sessionId: scope.sessionId, status, checkpointSequence: job.checkpoint.sequence });
+    return { job, duplicate: false, receipt, selfstarterPath: paths.selfstarterPath };
+  });
+}

package/agent-spine-plugin/src/lib/selfstarter-policy.js

@@ -0,0 +1,90 @@
+import { randomUUID } from "node:crypto";
+import {
+  ACTIONS, HOSTS, capabilities, emptyJobs, emptyPolicy, executionPolicyFindingsInternal,
+  normalizeJobs, normalizePolicy, pathsFor, preservePolicy, readJson, referenceState,
+  requireOwnerConfirmation, safeText, selfstarterFindingsInternal, stableId, timestamp,
+  validateGrantReferences, withLock
+} from "./selfstarter-core.js";
+
+export function executionPolicyFindings(policy, graph, coordination) {
+  return executionPolicyFindingsInternal(policy, graph, coordination);
+}
+
+export function selfstarterFindings(state, policy, graph, coordination) {
+  return selfstarterFindingsInternal(state, policy, graph, coordination);
+}
+
+export async function loadExecutionPolicy(root = process.cwd(), providedCatalog = null) {
+  const paths = await pathsFor(root, providedCatalog);
+  return { policy: await readJson(paths.executionPolicyPath, paths.catalog.root, normalizePolicy, emptyPolicy), ...paths };
+}
+
+export async function loadSelfstarter(root = process.cwd(), providedCatalog = null) {
+  const paths = await pathsFor(root, providedCatalog);
+  return { state: await readJson(paths.selfstarterPath, paths.catalog.root, normalizeJobs, emptyJobs), ...paths };
+}
+
+export async function inspectSelfstarter(root = process.cwd(), providedCatalog = null) {
+  const paths = await pathsFor(root, providedCatalog);
+  let policy = emptyPolicy(paths.catalog.root);
+  let state = emptyJobs(paths.catalog.root);
+  const errors = [];
+  try { policy = await readJson(paths.executionPolicyPath, paths.catalog.root, normalizePolicy, emptyPolicy); } catch (error) { errors.push(`policy:${error.message}`); }
+  try { state = await readJson(paths.selfstarterPath, paths.catalog.root, normalizeJobs, emptyJobs); } catch (error) { errors.push(`state:${error.message}`); }
+  return { policy, state, errors, ...paths };
+}
+
+export async function grantExecution({
+  root = process.cwd(), id = `execution-grant:${randomUUID()}`, actorId, actions = ["start", "resume", "effect"],
+  jobId, taskId, targetId, projectId, groupId = null, host, capabilities: requestedCapabilities,
+  reason, expiresAt = null, confirmation, now = new Date()
+}) {
+  requireOwnerConfirmation(confirmation);
+  const grant = {
+    id: stableId(id, "grantId"), actorId: stableId(actorId, "actorId"),
+    actions: [...new Set(actions)].sort(), jobId: stableId(jobId, "jobId"), taskId: stableId(taskId, "taskId"),
+    targetId: stableId(targetId, "targetId"), projectId: stableId(projectId, "projectId"),
+    groupId: stableId(groupId, "groupId", true), host, capabilities: capabilities(requestedCapabilities),
+    reason: safeText(reason, "reason", 500), active: true, expiresAt: timestamp(expiresAt, "expiresAt", true)
+  };
+  if (grant.actions.length !== 3 || grant.actions.some((action) => !ACTIONS.has(action))) throw new Error("a self-starter grant must explicitly include start, resume, and effect");
+  if (!HOSTS.has(host)) throw new Error("host must be claude or codex");
+  const at = timestamp(now, "now");
+  if (grant.expiresAt && new Date(grant.expiresAt) <= new Date(at)) throw new Error("execution grant expiry must be in the future");
+  const { catalog, executionPolicyPath } = await pathsFor(root);
+  const { graph, coordination } = await referenceState(catalog);
+  if (!validateGrantReferences(grant, graph, coordination)) throw new Error("execution grant must match a current assigned task and its exact scope");
+  return withLock(executionPolicyPath, () => readJson(executionPolicyPath, catalog.root, normalizePolicy, emptyPolicy), (policy) => {
+    const findings = executionPolicyFindingsInternal(policy, graph, coordination, { checkCurrentReferences: false });
+    if (findings.length) throw new Error(`execution policy failed closed: ${findings.join(", ")}`);
+    if (policy.grants.some((item) => item.id === grant.id || item.jobId === grant.jobId)) throw new Error("execution grant and job IDs are immutable and unique");
+    policy.revision += 1;
+    Object.assign(grant, {
+      revision: policy.revision, createdAt: at, updatedAt: at,
+      source: "explicit-local-owner-policy", authority: "explicit-local-execution-policy"
+    });
+    policy.grants.push(grant);
+    policy.grants.sort((a, b) => a.id.localeCompare(b.id));
+    return { grant, policyRevision: policy.revision, executionPolicyPath };
+  });
+}
+
+export async function revokeExecution({ root = process.cwd(), id, reason, confirmation, now = new Date() }) {
+  requireOwnerConfirmation(confirmation);
+  stableId(id, "grantId");
+  const at = timestamp(now, "now");
+  const revokeReason = safeText(reason, "reason", 500);
+  const { catalog, executionPolicyPath } = await pathsFor(root);
+  const { graph, coordination } = await referenceState(catalog);
+  return withLock(executionPolicyPath, () => readJson(executionPolicyPath, catalog.root, normalizePolicy, emptyPolicy), (policy) => {
+    const findings = executionPolicyFindingsInternal(policy, graph, coordination);
+    if (findings.length) throw new Error(`execution policy failed closed: ${findings.join(", ")}`);
+    const previous = policy.grants.find((grant) => grant.id === id);
+    if (!previous || !previous.active) throw new Error("execution grant is unknown or already revoked");
+    preservePolicy(policy, previous, at);
+    policy.revision += 1;
+    const grant = { ...previous, active: false, revokedAt: at, revokeReason, revision: policy.revision, updatedAt: at };
+    policy.grants = policy.grants.map((item) => item.id === id ? grant : item);
+    return { grant, policyRevision: policy.revision, executionPolicyPath };
+  });
+}

package/agent-spine-plugin/src/lib/selfstarter-workspace.js

@@ -0,0 +1,111 @@
+import { createHash } from "node:crypto";
+import { lstat, opendir, readFile, realpath } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+import { isConfiguredHostProfileRoot, workspaceScanError } from "./selfstarter-core.js";
+
+const MAX_WORKSPACE_FILES = 10000;
+const MAX_WORKSPACE_BYTES = 64 * 1024 * 1024;
+const EXCLUDED_NAMES = new Set([".git", "node_modules", ".DS_Store"]);
+
+export function skippableTraversalError(error) {
+  return ["EPERM", "EACCES", "ENOENT"].includes(error?.code);
+}
+
+export function skippedPath(skipped, path, error, operation) {
+  skipped.push({ path, code: error.code, operation });
+}
+
+export async function collectWorkspaceFiles(root) {
+  const files = [];
+  const skipped = [];
+  let totalBytes = 0;
+  async function walk(directory) {
+    let stream;
+    try {
+      stream = await opendir(directory);
+    } catch (error) {
+      if (!skippableTraversalError(error)) throw workspaceScanError(error);
+      skippedPath(skipped, error.path || directory, error, "opendir");
+      return;
+    }
+    const entries = [];
+    try {
+      for await (const entry of stream) entries.push(entry);
+    } catch (error) {
+      if (!skippableTraversalError(error)) throw workspaceScanError(error);
+      skippedPath(skipped, directory, error, "readdir");
+      return;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      if (EXCLUDED_NAMES.has(entry.name)) continue;
+      const path = join(directory, entry.name);
+      let metadata;
+      try {
+        metadata = await lstat(path);
+      } catch (error) {
+        if (!skippableTraversalError(error)) throw workspaceScanError(error);
+        skippedPath(skipped, error.path || path, error, "lstat");
+        continue;
+      }
+      if (metadata.isSymbolicLink()) {
+        try {
+          await realpath(path);
+        } catch (error) {
+          if (!skippableTraversalError(error)) throw workspaceScanError(error);
+          skippedPath(skipped, error.path || path, error, "realpath");
+          continue;
+        }
+        throw new Error(`workspace fingerprint rejects symbolic link: ${relative(root, path)}`);
+      }
+      if (metadata.isDirectory()) await walk(path);
+      else if (metadata.isFile()) {
+        files.push({ path, relativePath: relative(root, path).split(sep).join("/"), size: metadata.size });
+        totalBytes += metadata.size;
+        if (files.length > MAX_WORKSPACE_FILES || totalBytes > MAX_WORKSPACE_BYTES) {
+          throw new Error("workspace exceeds the self-starter fingerprint limit");
+        }
+      }
+    }
+  }
+  await walk(root);
+  return { files, skipped: skipped.sort((a, b) => a.path.localeCompare(b.path) || a.operation.localeCompare(b.operation)) };
+}
+
+export async function workspaceFingerprint(inputRoot = process.cwd()) {
+  const root = resolve(inputRoot);
+  if (isConfiguredHostProfileRoot(root)) {
+    throw new Error("self-starter cannot fingerprint a host profile root");
+  }
+  const collected = await collectWorkspaceFiles(root);
+  const files = [];
+  const skipped = [...collected.skipped];
+  const hash = createHash("sha256");
+  for (const file of collected.files) {
+    let content;
+    try {
+      content = await readFile(file.path);
+    } catch (error) {
+      if (!skippableTraversalError(error)) throw workspaceScanError(error);
+      skippedPath(skipped, error.path || file.path, error, "readFile");
+      continue;
+    }
+    files.push(file);
+    hash.update(file.relativePath).update("\0").update(String(file.size)).update("\0");
+    hash.update(content).update("\0");
+  }
+  return {
+    digest: hash.digest("hex"), files: files.length, bytes: files.reduce((sum, file) => sum + file.size, 0),
+    skipped: skipped.sort((a, b) => a.path.localeCompare(b.path) || a.operation.localeCompare(b.operation))
+  };
+}
+
+export function incompleteWorkspaceScan(skipped) {
+  const first = skipped[0];
+  const error = new Error(`workspace scan skipped ${skipped.length} inaccessible path${skipped.length === 1 ? "" : "s"}: ${first.path}`);
+  error.code = "AGENTSPINE_SCAN_INCOMPLETE";
+  error.path = first.path;
+  error.syscall = first.operation;
+  error.skipped = skipped;
+  return error;
+}