chainlesschain 0.166.140 → 0.166.142

package/src/lib/plugin-runtime/cli-goal-capabilities.js

@@ -0,0 +1,28 @@
+/** Implemented CLI surfaces; source leases and per-call activation still gate use. */
+import { VERSION } from "../../constants.js";
+
+export const CLI_GOAL_CAPABILITIES = Object.freeze([
+  "event:goal.status.changed",
+  "event:risk.review.completed",
+  "event:action.receipt.updated",
+  "panel:goal.summary",
+  "panel:goal.evidence",
+  "proposal:task.description.update",
+]);
+
+export function cliGoalExtensionHost(activeCapabilities) {
+  if (
+    !Array.isArray(activeCapabilities) ||
+    activeCapabilities.some(
+      (value) => !CLI_GOAL_CAPABILITIES.includes(value),
+    ) ||
+    new Set(activeCapabilities).size !== activeCapabilities.length
+  )
+    throw new Error("CLI_GOAL_HOST_CAPABILITIES_INVALID");
+  return Object.freeze({
+    id: "cli",
+    version: VERSION,
+    capabilities: CLI_GOAL_CAPABILITIES,
+    activeCapabilities: Object.freeze([...activeCapabilities]),
+  });
+}

package/src/lib/plugin-runtime/cli-goal-draft-request.js

@@ -1,15 +1,11 @@
 import fs from "node:fs";
 import path from "node:path";
-import { VERSION } from "../../constants.js";
+import { cliGoalExtensionHost } from "./cli-goal-capabilities.js";
 import { createProjectGoalConnection } from "../project-goal-connection.js";
 import { collectGoalExtensions } from "./goal-extensions.js";
 import { createGoalDraftRequest } from "@chainlesschain/session-core/goal-draft-request-contract";
 import { digestBusinessObjectContent as digest } from "@chainlesschain/session-core/business-object-contract";
-const HOST = Object.freeze({
-  id: "cli",
-  version: VERSION,
-  capabilities: Object.freeze(["proposal:task.description.update"]),
-});
+const HOST = cliGoalExtensionHost(["proposal:task.description.update"]);
 function fail(code) {
   throw new Error(code);
 }

package/src/lib/plugin-runtime/cli-goal-drafts.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { VERSION } from "../../constants.js";
+import { cliGoalExtensionHost } from "./cli-goal-capabilities.js";
 import { managedSettingsPath } from "../settings-loader.cjs";
 import { createProjectGoalConnection } from "../project-goal-connection.js";
 import {
@@ -20,11 +20,7 @@ import {
   validateGoalDraftSubmissionReference,
 } from "@chainlesschain/session-core/goal-draft-connection-contract";
 
-const HOST = Object.freeze({
-  id: "cli",
-  version: VERSION,
-  capabilities: Object.freeze(["proposal:task.description.update"]),
-});
+const HOST = cliGoalExtensionHost(["proposal:task.description.update"]);
 export const CLI_GOAL_DRAFT_SUBMISSION_SCHEMA =
   "chainlesschain.goal-draft-submission/v1";
 export const CLI_GOAL_DRAFT_SOURCES_SCHEMA =

package/src/lib/plugin-runtime/cli-goal-event-history.js

@@ -0,0 +1,284 @@
+/** One acknowledged page at a time; checkpoints contain no credentials or bodies. */
+import fs from "node:fs";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { cliGoalExtensionHost } from "./cli-goal-capabilities.js";
+import { managedSettingsPath } from "../settings-loader.cjs";
+import { withFileLockAsync } from "../with-file-lock.js";
+import { createProjectGoalConnection } from "../project-goal-connection.js";
+import {
+  collectGoalExtensions,
+  projectGoalExtensionEvent,
+} from "./goal-extensions.js";
+import { parseGoalEventCursor } from "@chainlesschain/session-core/goal-evidence-contract";
+const TYPES = ["risk.review.completed", "action.receipt.updated"];
+const hash = (value) =>
+  createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const fail = (code) => {
+  throw Object.assign(new Error(code), { code });
+};
+export const _deps = { createProjectGoalConnection, projectGoalExtensionEvent };
+const sameFile = (a, b) =>
+  a.dev === b.dev &&
+  a.ino === b.ino &&
+  a.size === b.size &&
+  a.mtimeMs === b.mtimeMs &&
+  a.ctimeMs === b.ctimeMs;
+function readFile(file) {
+  const entry = fs.lstatSync(file);
+  if (
+    !entry.isFile() ||
+    entry.isSymbolicLink() ||
+    entry.nlink !== 1 ||
+    entry.size > 8192
+  )
+    fail("GOAL_EVENT_CHECKPOINT_INVALID");
+  const fd = fs.openSync(
+    file,
+    fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0),
+  );
+  try {
+    if (!sameFile(entry, fs.fstatSync(fd)))
+      fail("GOAL_EVENT_CHECKPOINT_CHANGED");
+    const bytes = Buffer.alloc(entry.size + 1),
+      n = fs.readSync(fd, bytes, 0, bytes.length, 0);
+    if (
+      n !== entry.size ||
+      !sameFile(entry, fs.fstatSync(fd)) ||
+      !sameFile(entry, fs.lstatSync(file))
+    )
+      fail("GOAL_EVENT_CHECKPOINT_CHANGED");
+    const body = bytes.subarray(0, n).toString("utf8");
+    return { record: JSON.parse(body), digest: hash(body) };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+/** Publish must acknowledge flushed output; a crash before checkpoint commit replays. */
+export function replayCliGoalEvents(id, raw = {}, publish) {
+  const cwd = path.resolve(raw.cwd || process.cwd()),
+    env = Object.freeze({ ...(raw.env || process.env) });
+  const required = (value) => {
+    if (
+      typeof value !== "string" ||
+      !value ||
+      value.length > 4096 ||
+      /[\u0000-\u001f]/u.test(value)
+    )
+      fail("GOAL_EVENT_ARGUMENT_REQUIRED");
+    return value;
+  };
+  const connection = path.resolve(cwd, required(raw.connection)),
+    checkpoint = path.resolve(cwd, required(raw.checkpoint));
+  const name = required(raw.plugin),
+    scope = raw.scope,
+    expectedStore = raw.expectedStore;
+  const signal = raw.signal;
+  const checkpointMode = raw.checkpointMode ?? "auto";
+  if (!["auto", "new", "resume"].includes(checkpointMode))
+    fail("GOAL_EVENT_ARGUMENT_REQUIRED");
+  if (
+    !["user", "project", "local"].includes(scope) ||
+    typeof publish !== "function"
+  )
+    fail("GOAL_EVENT_ARGUMENT_REQUIRED");
+  const policyEnv = { ...env };
+  if (policyEnv.CC_MANAGED_SETTINGS)
+    policyEnv.CC_MANAGED_SETTINGS = path.resolve(
+      cwd,
+      required(policyEnv.CC_MANAGED_SETTINGS),
+    );
+  const policyFile = managedSettingsPath({
+    env: policyEnv,
+    managedSettingsFile:
+      raw.managedSettingsFile === undefined
+        ? undefined
+        : path.resolve(cwd, required(raw.managedSettingsFile)),
+  });
+  const options = Object.freeze({
+    cwd,
+    env,
+    managedSettingsFile: policyFile,
+    host: cliGoalExtensionHost(TYPES.map((type) => `event:${type}`)),
+  });
+  return (async () => {
+    const source = _deps.createProjectGoalConnection(connection);
+    if (!source.eventHistory || typeof source.readEventPage !== "function")
+      fail("GOAL_EVENT_HISTORY_CONNECTION_REQUIRED");
+    const goalRef = source.goalRef;
+    if (
+      goalRef.id !== id ||
+      (expectedStore !== undefined && expectedStore !== goalRef.storeId)
+    )
+      fail("CLI_GOAL_STORE_MISMATCH");
+    const selected = collectGoalExtensions(options).extensions.find(
+      (entry) =>
+        entry.name === name &&
+        entry.scope === scope &&
+        entry.declaration.events.some((type) => TYPES.includes(type)),
+    );
+    if (!selected) fail("CLI_GOAL_EVENT_PLUGIN_UNAVAILABLE");
+    const plugin = Object.freeze({
+        name: selected.name,
+        scope: selected.scope,
+        version: selected.version,
+      }),
+      declarationDigest = hash(selected.declaration);
+    function admission() {
+      if (signal?.aborted) fail("GOAL_EVENT_REPLAY_ABORTED");
+      const current = collectGoalExtensions(options).extensions.find(
+        (entry) =>
+          entry.name === name &&
+          entry.scope === scope &&
+          entry.version === plugin.version,
+      );
+      if (!current || hash(current.declaration) !== declarationDigest)
+        fail("CLI_GOAL_EVENT_ADMISSION_CHANGED");
+    }
+    admission();
+    const root = path.dirname(checkpoint),
+      realRoot = fs.realpathSync(root),
+      rootStat = fs.statSync(root);
+    const checkRoot = () => {
+      const stat = fs.statSync(root);
+      if (
+        fs.realpathSync(root) !== realRoot ||
+        !stat.isDirectory() ||
+        stat.dev !== rootStat.dev ||
+        stat.ino !== rootStat.ino
+      )
+        fail("GOAL_EVENT_CHECKPOINT_CHANGED");
+    };
+    const binding = {
+      schema: "chainlesschain.goal-event-checkpoint/v1",
+      goalRef,
+      plugin,
+      declarationDigest,
+    };
+    return withFileLockAsync(
+      checkpoint,
+      async (lock) => {
+        checkRoot();
+        admission();
+        const exists = fs.existsSync(checkpoint);
+        if (checkpointMode === "new" && exists)
+          fail("GOAL_EVENT_CHECKPOINT_EXISTS");
+        if (checkpointMode === "resume" && !exists)
+          fail("GOAL_EVENT_CHECKPOINT_MISSING");
+        if (!fs.existsSync(checkpoint)) {
+          const fd = fs.openSync(checkpoint, "wx", 0o600);
+          try {
+            fs.writeFileSync(fd, JSON.stringify({ ...binding, after: null }));
+            fs.fsyncSync(fd);
+          } finally {
+            fs.closeSync(fd);
+          }
+        }
+        const initial = readFile(checkpoint),
+          record = initial.record;
+        if (
+          !record ||
+          Object.keys(record).sort().join() !==
+            "after,declarationDigest,goalRef,plugin,schema" ||
+          hash({ ...record, after: null }) !== hash({ ...binding, after: null })
+        )
+          fail("GOAL_EVENT_CHECKPOINT_BINDING_CONFLICT");
+        if (record.after !== null) parseGoalEventCursor(record.after);
+        const after = record.after ?? undefined;
+        const page = await source.readEventPage(after, { signal });
+        admission();
+        const events = [];
+        for (const entry of page.entries) {
+          if (!selected.declaration.events.includes(entry.type)) continue;
+          const summary =
+            entry.type === "risk.review.completed"
+              ? `Historical risk check ${entry.sourceId}: ${entry.state}; risk task count ${entry.riskTaskCount ?? "unknown"}. This does not prove current risk or goal completion.`
+              : `Historical action receipt ${entry.sourceId}: ${entry.state} (${entry.actionType}). This does not prove goal completion.`;
+          const event = await _deps.projectGoalExtensionEvent(
+            plugin,
+            { type: entry.type, goalRef },
+            {
+              ...options,
+              authorize(context) {
+                admission();
+                return (
+                  context.operation === "read-event" &&
+                  context.type === entry.type &&
+                  hash(context.goalRef) === hash(goalRef)
+                );
+              },
+              readEvent() {
+                return { summary, occurredAt: entry.recordedAt };
+              },
+            },
+          );
+          events.push({
+            id: entry.id,
+            sequence: entry.sequence,
+            sourceRef: entry.sourceRef,
+            recordedAt: entry.recordedAt,
+            event,
+          });
+        }
+        async function revalidate() {
+          admission();
+          checkRoot();
+          if (readFile(checkpoint).digest !== initial.digest)
+            fail("GOAL_EVENT_CHECKPOINT_CHANGED");
+          const current = await source.readEventPage(after, { signal });
+          if (
+            hash(current.entries.slice(0, page.entries.length)) !==
+              hash(page.entries) ||
+            (page.nextCursor === null && current.nextCursor !== null) ||
+            (page.nextCursor &&
+              parseGoalEventCursor(page.nextCursor).epoch !==
+                parseGoalEventCursor(current.nextCursor).epoch)
+          )
+            fail("GOAL_EVENT_HISTORY_CHANGED");
+          admission();
+        }
+        await revalidate();
+        const result = {
+          schema: "chainlesschain.goal-extension-history/v1",
+          goalRef,
+          plugin,
+          observedAt: new Date().toISOString(),
+          delivery: "at-least-once",
+          entries: events,
+          scannedCount: page.entries.length,
+          nextCursor: page.nextCursor,
+          hasMore: page.hasMore,
+          truncated: page.truncated,
+          retainedFrom: page.retainedFrom,
+          highWatermark: page.highWatermark,
+        };
+        if ((await publish(Object.freeze(result))) !== true)
+          fail("GOAL_EVENT_OUTPUT_NOT_ACKNOWLEDGED");
+        await revalidate();
+        lock.assertOwnership();
+        const temporary = `${checkpoint}.${randomUUID()}.tmp`;
+        try {
+          const fd = fs.openSync(temporary, "wx", 0o600);
+          try {
+            fs.writeFileSync(
+              fd,
+              JSON.stringify({ ...binding, after: page.nextCursor }),
+            );
+            fs.fsyncSync(fd);
+          } finally {
+            fs.closeSync(fd);
+          }
+          checkRoot();
+          lock.assertOwnership();
+          if (readFile(checkpoint).digest !== initial.digest)
+            fail("GOAL_EVENT_CHECKPOINT_CHANGED");
+          fs.renameSync(temporary, checkpoint);
+        } finally {
+          if (fs.existsSync(temporary)) fs.unlinkSync(temporary);
+        }
+        return { checkpoint, hasMore: page.hasMore };
+      },
+      { failIfUnavailable: true, timeoutMs: 2000 },
+    );
+  })();
+}

package/src/lib/plugin-runtime/cli-goal-events.js

@@ -0,0 +1,175 @@
+/** Explicit, bounded polling of standalone goal status. No durable event log. */
+import path from "node:path";
+import { performance } from "node:perf_hooks";
+import { setTimeout as delay } from "node:timers/promises";
+import { cliGoalExtensionHost } from "./cli-goal-capabilities.js";
+import { resolveConfigDataRoot } from "../paths.js";
+import { managedSettingsPath } from "../settings-loader.cjs";
+import { createCliGoalSnapshotReader } from "../cli-goal-source.js";
+import {
+  collectGoalExtensions,
+  projectGoalExtensionEvent,
+} from "./goal-extensions.js";
+
+const TYPE = "goal.status.changed";
+export const CLI_GOAL_EVENT_SCHEMA = "chainlesschain.goal-extension-stream/v1";
+export const _deps = { projectGoalExtensionEvent };
+const fail = (code) => {
+  throw new Error(code);
+};
+
+/** Capture selection synchronously; retained iterators never change workspace. */
+export function watchCliGoalExtensionEvents(id, options = {}) {
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const env = Object.freeze({ ...(options.env || process.env) });
+  const root = path.resolve(
+    options.root ||
+      path.join(resolveConfigDataRoot({ cwd, env }).path, "goals"),
+  );
+  const managedSettingsFile = managedSettingsPath({
+    env,
+    managedSettingsFile: options.managedSettingsFile,
+  });
+  const name = options.plugin,
+    scope = options.scope;
+  const expectedStore = options.expectedStore;
+  const intervalMs = options.intervalMs ?? 1000;
+  const durationMs = options.durationMs ?? 60000;
+  const signal = options.signal;
+  if (options.connection !== undefined) fail("CLI_GOAL_EVENTS_STANDALONE_ONLY");
+  if (typeof name !== "string" || !name || name.length > 256)
+    fail("CLI_GOAL_INVALID_PLUGIN_NAME");
+  if (scope !== undefined && !["user", "project", "local"].includes(scope))
+    fail("CLI_GOAL_INVALID_PLUGIN_SCOPE");
+  if (
+    !Number.isSafeInteger(intervalMs) ||
+    intervalMs < 250 ||
+    intervalMs > 60000 ||
+    !Number.isSafeInteger(durationMs) ||
+    durationMs < 1000 ||
+    durationMs > 900000
+  )
+    fail("CLI_GOAL_INVALID_WATCH_LIMIT");
+  if (signal !== undefined && !(signal instanceof AbortSignal))
+    fail("CLI_GOAL_INVALID_WATCH_SIGNAL");
+  const host = cliGoalExtensionHost([`event:${TYPE}`]);
+  const admission = Object.freeze({ cwd, env, managedSettingsFile, host });
+
+  return (async function* () {
+    if (signal?.aborted) return;
+    const source = createCliGoalSnapshotReader(root);
+    if (expectedStore !== undefined && expectedStore !== source.storeId)
+      fail("CLI_GOAL_STORE_MISMATCH");
+    const matches = collectGoalExtensions(admission).extensions.filter(
+      (entry) =>
+        entry.name === name &&
+        (!scope || entry.scope === scope) &&
+        entry.declaration.events.includes(TYPE),
+    );
+    if (matches.length !== 1) fail("CLI_GOAL_EVENT_PLUGIN_UNAVAILABLE");
+    const plugin = matches[0];
+    const ref = Object.freeze({
+      name: plugin.name,
+      scope: plugin.scope,
+      version: plugin.version,
+    });
+    const declaration = JSON.stringify(plugin.declaration);
+    function revalidatePlugin() {
+      const current = collectGoalExtensions(admission).extensions.find(
+        (entry) =>
+          entry.name === ref.name &&
+          entry.scope === ref.scope &&
+          entry.version === ref.version,
+      );
+      if (!current || JSON.stringify(current.declaration) !== declaration)
+        fail("CLI_GOAL_EVENT_ADMISSION_CHANGED");
+    }
+    const reference = (goal) =>
+      Object.freeze({
+        id: goal.id,
+        storeId: goal.storeId,
+        revision: goal.revision,
+        controlGeneration: goal.controlGeneration,
+      });
+    let snapshot = source.read(id);
+    source.revalidate(snapshot);
+    revalidatePlugin();
+    const deadline = performance.now() + durationMs;
+    yield Object.freeze({
+      schema: CLI_GOAL_EVENT_SCHEMA,
+      kind: "ready",
+      plugin: ref,
+      goalRef: reference(snapshot.goal),
+      observedAt: new Date().toISOString(),
+      delivery: "polling",
+      replay: false,
+    });
+    while (!signal?.aborted && performance.now() < deadline) {
+      try {
+        await delay(
+          Math.min(intervalMs, Math.max(1, deadline - performance.now())),
+          undefined,
+          { signal },
+        );
+      } catch (error) {
+        if (signal?.aborted && error.name === "AbortError") return;
+        throw error;
+      }
+      if (signal?.aborted || performance.now() >= deadline) return;
+      revalidatePlugin();
+      const current = source.read(id);
+      if (
+        current.goal.revision < snapshot.goal.revision ||
+        current.goal.controlGeneration < snapshot.goal.controlGeneration
+      )
+        fail("CLI_GOAL_EVENT_SOURCE_REGRESSED");
+      if (current.digest === snapshot.digest) continue;
+      const previousStatus = snapshot.goal.status;
+      if (current.goal.status === previousStatus) {
+        snapshot = current;
+        continue;
+      }
+      const goalRef = reference(current.goal);
+      // occurredAt is observation time: polling cannot establish mutation time.
+      const observedAt = new Date().toISOString();
+      const event = await _deps.projectGoalExtensionEvent(
+        ref,
+        { type: TYPE, goalRef },
+        {
+          ...admission,
+          authorize(context) {
+            if (
+              context.operation !== "read-event" ||
+              context.type !== TYPE ||
+              JSON.stringify(context.goalRef) !== JSON.stringify(goalRef)
+            )
+              return false;
+            source.revalidate(current);
+            revalidatePlugin();
+            return true;
+          },
+          readEvent() {
+            source.revalidate(current);
+            return {
+              summary: `status: ${previousStatus} -> ${current.goal.status}`,
+              occurredAt: observedAt,
+            };
+          },
+        },
+      );
+      source.revalidate(current);
+      revalidatePlugin();
+      if (signal?.aborted || performance.now() >= deadline) return;
+      snapshot = current;
+      yield Object.freeze({
+        schema: CLI_GOAL_EVENT_SCHEMA,
+        kind: "event",
+        plugin: ref,
+        observedAt,
+        delivery: "polling",
+        replay: false,
+        event,
+      });
+    }
+  })();
+}

package/src/lib/plugin-runtime/cli-goal-extension-host.js

@@ -1,7 +1,7 @@
 /** Explicit goal panels from standalone files or a short-lived desktop read lease. */
 import path from "node:path";
 import { createHash } from "node:crypto";
-import { VERSION } from "../../constants.js";
+import { cliGoalExtensionHost } from "./cli-goal-capabilities.js";
 import { resolveConfigDataRoot } from "../paths.js";
 import { managedSettingsPath } from "../settings-loader.cjs";
 import { createCliGoalSnapshotReader } from "../cli-goal-source.js";
@@ -13,11 +13,9 @@ import {
 } from "./goal-extensions.js";
 
 export const CLI_GOAL_PANEL_SCHEMA = "chainlesschain.goal-extension-panels.v1";
-export const CLI_GOAL_EXTENSION_HOST = Object.freeze({
-  id: "cli",
-  version: VERSION,
-  capabilities: Object.freeze(["panel:goal.summary"]),
-});
+export const CLI_GOAL_EXTENSION_HOST = cliGoalExtensionHost([
+  "panel:goal.summary",
+]);
 export const _deps = { collectGoalExtensions, projectGoalExtensionPanel };
 
 function fail(code) {
@@ -95,13 +93,7 @@ export async function readCliGoalExtensionPanels(id, options = {}) {
     env,
     managedSettingsFile,
     host: connection?.evidence
-      ? Object.freeze({
-          ...CLI_GOAL_EXTENSION_HOST,
-          capabilities: Object.freeze([
-            "panel:goal.summary",
-            "panel:goal.evidence",
-          ]),
-        })
+      ? cliGoalExtensionHost(["panel:goal.summary", "panel:goal.evidence"])
       : CLI_GOAL_EXTENSION_HOST,
     async authorize(context) {
       if (
@@ -169,6 +161,22 @@ export async function readCliGoalExtensionPanels(id, options = {}) {
     const projected = [];
     try {
       for (const panel of plugin.declaration.panels) {
+        if (
+          !hostOptions.host.activeCapabilities.includes(`panel:${panel.slot}`)
+        ) {
+          if (
+            !dropped.some(
+              (entry) =>
+                entry.name === plugin.name && entry.scope === plugin.scope,
+            )
+          )
+            dropped.push({
+              name: plugin.name,
+              scope: plugin.scope,
+              reason: "unsupported_capabilities",
+            });
+          continue;
+        }
         projected.push({
           plugin: ref,
           ...(await _deps.projectGoalExtensionPanel(