@kontourai/flow-agents 3.7.0 → 3.9.0

package/scripts/install-codex-home.sh

@@ -16,14 +16,21 @@ Options:
   --console-token-file PATH
                           Read Console telemetry bearer token from a file.
   --console-tenant ID     Persist Console tenant identifier.
+  --skills-dir PATH       Install portable skills here (default: $HOME/.agents/skills).
 EOF
 }
 
 DEST="${CODEX_HOME:-$HOME/.codex}"
+SKILLS_DIR="${FLOW_AGENTS_SKILLS_DIR:-$HOME/.agents/skills}"
 DEST_SET=0
 CONSOLE_CONFIG_ARGS=()
 while [[ $# -gt 0 ]]; do
   case "$1" in
+    --skills-dir)
+      [[ $# -ge 2 ]] || { echo "install-codex-home.sh: $1 requires a value" >&2; exit 2; }
+      SKILLS_DIR="$2"
+      shift 2
+      ;;
     --telemetry-sink|--telemetry-sinks|--console-url|--console-endpoint|--console-endpoint-url|--console-token-file|--console-tenant|--console-tenant-id)
       [[ $# -ge 2 ]] || { echo "install-codex-home.sh: $1 requires a value" >&2; exit 2; }
       CONSOLE_CONFIG_ARGS+=("$1" "$2")
@@ -69,9 +76,26 @@ NODE
 }
 
 [[ ! -L "$DEST" ]] || { echo "install-codex-home.sh: refusing symlink destination root: $DEST" >&2; exit 1; }
+[[ ! -L "$SKILLS_DIR" ]] || { echo "install-codex-home.sh: refusing symlink skills destination root: $SKILLS_DIR" >&2; exit 1; }
 ROOT_REAL="$(canonicalize_path "$ROOT_DIR")"
 BUNDLE_SOURCE_REAL="$(canonicalize_path "$ROOT_DIR/dist/codex")"
 DEST_REAL="$(canonicalize_path "$DEST")"
+SKILLS_DIR_REAL="$(canonicalize_path "$SKILLS_DIR")"
+if ! node - "$SKILLS_DIR" <<'NODE'
+const fs = require("node:fs"); const path = require("node:path");
+const absolute = path.resolve(process.argv[2]);
+let current = path.parse(absolute).root;
+for (const part of absolute.slice(current.length).split(path.sep).filter(Boolean)) {
+  current = path.join(current, part);
+  // macOS exposes /tmp as the system-managed /private/tmp symlink. Treat that
+  // mount alias as trusted while rejecting caller-controlled components.
+  if (current !== "/tmp" && fs.existsSync(current) && fs.lstatSync(current).isSymbolicLink()) process.exit(1);
+}
+NODE
+then
+  echo "install-codex-home.sh: refusing symlink component in skills destination: $SKILLS_DIR" >&2
+  exit 1
+fi
 REAL_CODEX_HOME_REAL="$(canonicalize_path "$REAL_CODEX_HOME")"
 case "$DEST_REAL/" in
   "$ROOT_REAL/"*|"$BUNDLE_SOURCE_REAL/"*)
@@ -85,6 +109,17 @@ case "$ROOT_REAL/" in
     exit 1
     ;;
 esac
+case "$SKILLS_DIR_REAL/" in
+  "$ROOT_REAL/"*|"$BUNDLE_SOURCE_REAL/"*) echo "install-codex-home.sh: skills destination overlaps Flow Agents source: $SKILLS_DIR_REAL" >&2; exit 1 ;;
+esac
+case "$ROOT_REAL/" in
+  "$SKILLS_DIR_REAL/"*) echo "install-codex-home.sh: Flow Agents source overlaps skills destination: $SKILLS_DIR_REAL" >&2; exit 1 ;;
+esac
+case "$BUNDLE_SOURCE_REAL/" in
+  "$SKILLS_DIR_REAL/"*) echo "install-codex-home.sh: generated bundle source overlaps skills destination: $SKILLS_DIR_REAL" >&2; exit 1 ;;
+esac
+SKILLS_PATH_ROOT="$(node -e 'process.stdout.write(require("node:path").parse(process.argv[1]).root)' "$SKILLS_DIR_REAL")"
+[[ "$SKILLS_DIR_REAL" != "$SKILLS_PATH_ROOT" ]] || { echo "install-codex-home.sh: refusing filesystem-root skills destination: $SKILLS_DIR_REAL" >&2; exit 1; }
 
 if command -v npm >/dev/null 2>&1; then
   (cd "$ROOT_DIR" && FLOW_AGENTS_EXPORT_DIAGNOSTICS=0 npm run build:bundles --silent >/dev/null)
@@ -93,10 +128,6 @@ else
   exit 1
 fi
 
-mkdir -p "$DEST"
-DEST="$(cd "$DEST" && pwd -P)"
-DEST_REAL="$DEST"
-
 assert_safe_dest_path() {
   local rel="$1"
   local current="$DEST"
@@ -122,22 +153,17 @@ assert_safe_dest_path() {
   esac
 }
 
-# Stash the user's existing hooks.json (if any), so the merge step below can
-# preserve user hooks across installs while replacing Flow Agents-managed groups.
 FA_USER_HOOKS_STASH=""
-assert_safe_dest_path "hooks.json"
-if [[ -f "$DEST/hooks.json" ]]; then
-  FA_USER_HOOKS_STASH="$(mktemp /tmp/fa-user-hooks.XXXXXX.json)"
-  cp "$DEST/hooks.json" "$FA_USER_HOOKS_STASH"
-fi
 
 # A real Codex home can contain user-owned files in every shared directory.
 # Prepare an exact Flow Agents overlay, then synchronize only files recorded in
 # the ownership manifest. The synchronizer never uses directory-wide --delete:
 # it removes only unchanged files from its prior manifest and refuses collisions.
 FA_OWNED_OVERLAY="$(mktemp -d /tmp/fa-codex-overlay.XXXXXX)"
+FA_SKILLS_OVERLAY="$(mktemp -d /tmp/fa-codex-skills-overlay.XXXXXX)"
 cleanup_install_temps() {
   rm -rf "$FA_OWNED_OVERLAY"
+  rm -rf "$FA_SKILLS_OVERLAY"
   [[ -z "${FA_USER_HOOKS_STASH:-}" ]] || rm -f "$FA_USER_HOOKS_STASH"
 }
 trap cleanup_install_temps EXIT
@@ -157,22 +183,14 @@ for managed_dir in \
   scripts
 do
   if [[ -d "$ROOT_DIR/dist/codex/$managed_dir" ]]; then
-    assert_safe_dest_path "$managed_dir"
     mkdir -p "$FA_OWNED_OVERLAY/$managed_dir"
     rsync -a "$ROOT_DIR/dist/codex/$managed_dir/" "$FA_OWNED_OVERLAY/$managed_dir/"
   fi
 done
 
-# Skills are user-extensible in a real Codex home. Merge both bundle skill
-# layers into the flattened destination without deleting user-owned skills.
-if [[ -d "$ROOT_DIR/dist/codex/skills" ]]; then
-  mkdir -p "$FA_OWNED_OVERLAY/skills"
-  rsync -a "$ROOT_DIR/dist/codex/skills/" "$FA_OWNED_OVERLAY/skills/"
-fi
-
-if [[ -d "$ROOT_DIR/dist/codex/.codex/skills" ]]; then
-  mkdir -p "$FA_OWNED_OVERLAY/skills"
-  rsync -a "$ROOT_DIR/dist/codex/.codex/skills/" "$FA_OWNED_OVERLAY/skills/"
+# Portable skills use Codex's universal catalog, independently of CODEX_HOME.
+if [[ -d "$ROOT_DIR/dist/codex/.agents/skills" ]]; then
+  rsync -a "$ROOT_DIR/dist/codex/.agents/skills/" "$FA_SKILLS_OVERLAY/"
 fi
 
 if [[ -d "$ROOT_DIR/dist/codex/kits" ]]; then
@@ -193,10 +211,31 @@ for bundle_file in README.md console.telemetry.json install.sh; do
   fi
 done
 
-assert_safe_dest_path ".flow-agents/codex-install-manifest.json"
+# Check both destinations with the exact synchronizer before either can mutate.
+node "$ROOT_DIR/scripts/install-owned-files.js" \
+  --check "$FA_SKILLS_OVERLAY" "$SKILLS_DIR_REAL" ".flow-agents/codex-universal-skills-install-manifest.json"
+node "$ROOT_DIR/scripts/install-owned-files.js" \
+  --check "$FA_OWNED_OVERLAY" "$DEST_REAL" ".flow-agents/codex-install-manifest.json"
+
+mkdir -p "$SKILLS_DIR"
+SKILLS_DIR="$(cd "$SKILLS_DIR" && pwd -P)"
+node "$ROOT_DIR/scripts/install-owned-files.js" \
+  "$FA_SKILLS_OVERLAY" "$SKILLS_DIR" ".flow-agents/codex-universal-skills-install-manifest.json"
+
+mkdir -p "$DEST"
+DEST="$(cd "$DEST" && pwd -P)"
+DEST_REAL="$DEST"
 node "$ROOT_DIR/scripts/install-owned-files.js" \
   "$FA_OWNED_OVERLAY" "$DEST" ".flow-agents/codex-install-manifest.json"
 
+# Stash the user's existing hooks.json (if any), so the merge step below can
+# preserve user hooks across installs while replacing Flow Agents-managed groups.
+assert_safe_dest_path "hooks.json"
+if [[ -f "$DEST/hooks.json" ]]; then
+  FA_USER_HOOKS_STASH="$(mktemp /tmp/fa-user-hooks.XXXXXX.json)"
+  cp "$DEST/hooks.json" "$FA_USER_HOOKS_STASH"
+fi
+
 atomic_copy() {
   local source="$1"
   local rel="$2"
@@ -289,6 +328,7 @@ if [[ ${#CONSOLE_CONFIG_ARGS[@]} -gt 0 || -n "${FLOW_AGENTS_TELEMETRY_SINK:-}" |
 fi
 
 echo "Installed Flow Agents into Codex home at $DEST"
+echo "Installed portable skills at $SKILLS_DIR"
 if [[ "${#profile_names[@]}" -gt 0 ]]; then
   echo "Profiles: ${profile_names[*]}"
 fi

package/scripts/install-owned-files.js

@@ -9,10 +9,24 @@ function fail(message) {
   process.exit(1);
 }
 
-const [sourceArg, destArg, manifestArg] = process.argv.slice(2);
+const args = process.argv.slice(2);
+const checkOnly = args[0] === "--check";
+if (checkOnly) args.shift();
+const [sourceArg, destArg, manifestArg] = args;
 if (!sourceArg || !destArg || !manifestArg) fail("usage: install-owned-files.js <overlay> <destination> <manifest-relative-path>");
 const source = fs.realpathSync(sourceArg);
-const dest = fs.realpathSync(destArg);
+function canonicalizeMissing(value) {
+  let current = path.resolve(value);
+  const missing = [];
+  while (!fs.existsSync(current)) {
+    missing.unshift(path.basename(current));
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return path.resolve(fs.realpathSync(current), ...missing);
+}
+const dest = canonicalizeMissing(destArg);
 const manifestPath = path.join(dest, manifestArg);
 
 function hashFile(file) {
@@ -132,6 +146,8 @@ for (const [rel] of previous) {
   if (fs.existsSync(target) && fs.lstatSync(target).isSymbolicLink()) fail(`refusing to remove symlink replacing owned file: ${target}`);
 }
 
+if (checkOnly) process.exit(0);
+
 for (const entry of incoming) {
   const target = targetFor(entry.rel);
   ensureSafeParent(target, true);

package/src/builder-flow-runtime.ts

@@ -367,10 +367,21 @@ async function syncAndProject(
     const snapshot = stageTrustBundleSnapshot(context);
     try {
       const rawBundle = JSON.parse(snapshot.raw.toString("utf8"));
-      const gateEvidence = await bundleGateEvidence(rawBundle, gates[0]!, run.state.subject, context.projectRoot);
+      const gateEvidence = await bundleGateEvidence(
+        rawBundle,
+        gates[0]!,
+        run.state,
+        run.state.subject,
+        context.projectRoot,
+        manifestEvidence(run.manifest),
+      );
       if (gateEvidence) {
         const alreadyAttached = manifestEvidence(run.manifest).some((entry) =>
-          entry.gate_id === gates[0]!.id && entry.sha256 === snapshot.sha256
+          entry.gate_id === gates[0]!.id
+          && entry.sha256 === snapshot.sha256
+          && typeof entry.superseded_by !== "string"
+          && timestampAtOrAfter(entry.attached_at, gateEvidence.visitEnteredAt)
+          && gateEvidence.expectationIds.every((expectationId) => Array.isArray(entry.expectation_ids) && entry.expectation_ids.includes(expectationId))
         );
         if (!alreadyAttached) {
           const supersede = manifestEvidence(run.manifest)
@@ -386,6 +397,7 @@ async function syncAndProject(
               ...(supersede.length > 0 ? { supersede } : {}),
               ...(gateEvidence.failed ? { status: "failed" } : {}),
               ...(gateEvidence.routeReason ? { routeReason: gateEvidence.routeReason } : {}),
+              expectationIds: gateEvidence.expectationIds,
             },
           });
           attached = true;
@@ -478,21 +490,72 @@ function openGatesForResult(run: BuilderFlowRunResult): Array<FlowGate & { id: s
   ) as Array<FlowGate & { id: string }>;
 }
 
-async function bundleGateEvidence(bundle: unknown, gate: FlowGate, subject: string, projectRoot: string): Promise<{ failed: boolean; routeReason: string | null } | null> {
+async function bundleGateEvidence(
+  bundle: unknown,
+  gate: FlowGate,
+  state: FlowRunState,
+  subject: string,
+  projectRoot: string,
+  manifest: AnyRecord[],
+): Promise<{ failed: boolean; routeReason: string | null; expectationIds: string[]; visitEnteredAt: number } | null> {
   if (!isRecord(bundle) || !Array.isArray(bundle.claims)) return null;
-  const selectors = (expectationsForGate(gate) as FlowExpectation[]).map((expectation) => expectation.bundle_claim);
+  const expectations = expectationsForGate(gate) as FlowExpectation[];
+  const visit = currentGateVisit(state, String((gate as AnyRecord).step));
+  const enteredAt = visit.enteredAt;
+  const synchronizedAt = Date.now();
+  const maxClockSkewMs = 30_000;
+  const priorVisitClaimIds = new Set<string>();
+  const priorVisitEvidenceIds = new Set<string>();
+  for (const entry of manifest) {
+    if (entry.gate_id !== String((gate as AnyRecord).id)) continue;
+    const claims = isRecord(entry.bundle) && Array.isArray(entry.bundle.claims) ? entry.bundle.claims : [];
+    for (const historical of claims) {
+      if (isRecord(historical) && typeof historical.id === "string") priorVisitClaimIds.add(historical.id);
+    }
+    const evidence = isRecord(entry.bundle) && Array.isArray(entry.bundle.evidence) ? entry.bundle.evidence : [];
+    for (const historical of evidence) {
+      if (isRecord(historical) && typeof historical.id === "string") priorVisitEvidenceIds.add(historical.id);
+    }
+  }
+  const claimIsCurrent = (claim: AnyRecord): boolean => {
+    if (typeof claim.id !== "string" || priorVisitClaimIds.has(claim.id)) return false;
+    const timestamps: number[] = [];
+    const createdAt = parseTimestamp(claim.createdAt);
+    if (createdAt !== null) timestamps.push(createdAt);
+    if (Array.isArray((bundle as AnyRecord).evidence)) for (const evidence of (bundle as AnyRecord).evidence) {
+      if (!isRecord(evidence) || evidence.claimId !== claim.id) continue;
+      if (typeof evidence.id !== "string" || priorVisitEvidenceIds.has(evidence.id)) return false;
+      const observedAt = parseTimestamp(evidence.observedAt);
+      if (observedAt !== null) timestamps.push(observedAt);
+    }
+    const initialAcquisitionSkew = visit.initial && claim.claimType === "builder.pull-work.selected" ? maxClockSkewMs : 0;
+    return timestamps.some((timestamp) => timestamp >= enteredAt - initialAcquisitionSkew
+      && timestamp <= synchronizedAt + maxClockSkewMs);
+  };
   const relevant = bundle.claims.filter((claim: unknown): claim is AnyRecord => {
     if (!isRecord(claim)) return false;
-    return selectors.some((candidate: FlowExpectation["bundle_claim"]) =>
+    if (claim.producerStatus === "superseded") return false;
+    const metadata = isRecord(claim.metadata) ? claim.metadata : null;
+    if (metadata && typeof metadata.superseded_by === "string") return false;
+    return expectations.some((expectation) => {
+      const candidate = expectation.bundle_claim;
+      return candidate
+      && claimIsCurrent(claim)
+      &&
       candidate.claimType === claim.claimType
       && (!candidate.subjectType || candidate.subjectType === claim.subjectType)
-    );
+    });
   });
   if (relevant.length === 0) return null;
   if (relevant.some((claim) => workflowSubjectRef(claim) !== subject)) {
     throw new BuilderBuildRunInputError("evidence.claims.metadata.workflow_subject_ref", "must match the persisted run subject");
   }
   const failed = relevant.some((claim) => claim.value === "fail" || claim.status === "disputed");
+  const expectationIds = expectations.filter((expectation) => relevant.some((claim: AnyRecord) => {
+    const selector = expectation.bundle_claim;
+    return selector.claimType === claim.claimType && (!selector.subjectType || selector.subjectType === claim.subjectType);
+  })).map((expectation) => expectation.id);
+  const missingRequired = expectations.filter((expectation) => expectation.required && !expectationIds.includes(expectation.id));
   const routeReasons = [...new Set(relevant.flatMap((claim) => {
     const metadata = isRecord(claim.metadata) ? claim.metadata : null;
     const gateClaim = metadata && isRecord(metadata.gate_claim) ? metadata.gate_claim : null;
@@ -502,6 +565,11 @@ async function bundleGateEvidence(bundle: unknown, gate: FlowGate, subject: stri
     throw new BuilderBuildRunInputError("evidence.claims.metadata.gate_claim.route_reason", "must agree across current-gate claims");
   }
   const routeReason = routeReasons[0] ?? null;
+  if (failed && !routeReason) return null;
+  // Passing evidence waits for the complete expectation set. A failing
+  // snapshot is complete only when a gate producer explicitly declares its
+  // route reason; report-only disputed critique state remains pending.
+  if (!failed && missingRequired.length > 0) return null;
   if (routeReason && !failed) {
     throw new BuilderBuildRunInputError("evidence.claims.metadata.gate_claim.route_reason", "requires failed current-gate evidence");
   }
@@ -512,7 +580,31 @@ async function bundleGateEvidence(bundle: unknown, gate: FlowGate, subject: stri
   if (String((gate as AnyRecord).id) === "verify-gate" && relevant.some((claim) => claim.claimType === "builder.verify.tests" && claim.value === "pass")) {
     await assertVerifiedTestsTrust(bundle.claims, projectRoot);
   }
-  return { failed, routeReason };
+  return { failed, routeReason, expectationIds, visitEnteredAt: enteredAt };
+}
+
+function currentGateVisit(state: FlowRunState, step: string): { enteredAt: number; initial: boolean } {
+  let enteredAt: number | null = null;
+  for (const transition of state.transitions ?? []) {
+    if (transition.to_step !== step) continue;
+    const parsed = parseTimestamp(transition.at);
+    if (parsed !== null) enteredAt = parsed;
+  }
+  const initial = parseTimestamp(state.updated_at);
+  if (enteredAt !== null) return { enteredAt, initial: false };
+  if (initial !== null) return { enteredAt: initial, initial: true };
+  throw new BuilderBuildRunInputError("flow_run.state.updated_at", "must establish the current gate visit boundary");
+}
+
+function parseTimestamp(value: unknown): number | null {
+  if (typeof value !== "string") return null;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function timestampAtOrAfter(value: unknown, boundary: number): boolean {
+  const parsed = parseTimestamp(value);
+  return parsed !== null && parsed >= boundary;
 }
 
 async function assertVerifiedTestsTrust(claims: unknown[], projectRoot: string): Promise<void> {
@@ -769,7 +861,9 @@ function projectFlowRun(context: SessionContext, run: BuilderFlowRunResult, side
   const complete = run.state.status === "completed";
   const paused = run.state.status === "paused";
   const canceled = run.state.status === "canceled";
-  const action = complete || paused || canceled ? { skills: [], operations: [] } : stepAction(run.definitionId, run.state.current_step);
+  const needsDecision = run.state.status === "needs_decision";
+  const failed = run.state.status === "failed";
+  const action = complete || paused || canceled || needsDecision || failed ? { skills: [], operations: [] } : stepAction(run.definitionId, run.state.current_step);
   if (!action) {
     throw new BuilderBuildRunInputError("kit.flow_step_actions", `does not declare Builder step ${run.state.current_step}`);
   }
@@ -794,6 +888,10 @@ function projectFlowRun(context: SessionContext, run: BuilderFlowRunResult, side
       ? { status: "done", summary: "Canonical Flow run was canceled by an authorized external request. Artifacts are retained until separately archived." }
       : paused
         ? { status: "blocked", summary: "Canonical Flow run is paused. The current assignment actor may resume it with a reason." }
+      : needsDecision
+        ? { status: "blocked", summary: "Canonical Flow requires an external decision before continuation." }
+      : failed
+        ? { status: "failed", summary: "Canonical Flow run failed; no continuation turn is allowed." }
     : {
         status: "continue",
         summary: `Flow step \`${run.state.current_step}\`: ${skillText}${operationText} ${gateText}${routeText} Then synchronize the recorded evidence.`,
@@ -804,8 +902,8 @@ function projectFlowRun(context: SessionContext, run: BuilderFlowRunResult, side
   const phase = phaseForStep(definition.phase_map, run.state.current_step) ?? sidecar.phase;
   return {
     ...sidecar,
-    status: complete ? "delivered" : canceled ? "canceled" : paused ? "blocked" : (run.state.transitions.length > 0 ? "in_progress" : sidecar.status),
-    phase: complete || canceled ? "done" : phase,
+    status: complete ? "delivered" : canceled ? "canceled" : failed ? "failed" : (paused || needsDecision) ? "blocked" : (run.state.transitions.length > 0 ? "in_progress" : sidecar.status),
+    phase: complete || canceled || failed ? "done" : phase,
     updated_at: run.state.updated_at,
     flow_run: {
       run_id: run.runId,

package/src/cli/assignment-provider.ts

@@ -775,7 +775,19 @@ export function performLocalReleaseUnderLock(
       // seam, relocated to this write path).
       const holderActorKey = existing.actor_key || helper.serializeActor(existing.actor);
       const releasedByActorKey = opts.actorKey || helper.serializeActor(releasedBy);
-      if (holderActorKey !== releasedByActorKey) {
+      // Pre-3.7 lifecycle events could persist the derived ancestry actor before
+      // sanitizeSegment removed ':' separators. Modern explicit/env release paths
+      // always use the sanitized form. Accept only that one-way legacy migration;
+      // never normalize two modern keys or relax ownership to a prefix match.
+      const sameActorStruct = existing.actor.runtime === releasedBy.runtime
+        && existing.actor.session_id === releasedBy.session_id
+        && existing.actor.host === releasedBy.host
+        && (existing.actor.human ?? null) === (releasedBy.human ?? null);
+      const legacyActorKeyMatches = holderActorKey.includes(":")
+        && holderActorKey === helper.serializeActor(existing.actor)
+        && helper.sanitizeSegment(holderActorKey) === releasedByActorKey
+        && sameActorStruct;
+      if (holderActorKey !== releasedByActorKey && !legacyActorKeyMatches) {
         if (tolerateNoActiveClaim) return null;
         throw new Error(`--actor-json does not match the current holder (${holderActorKey}); refusing to release a claim held by someone else`);
       }