@kontourai/flow-agents 3.6.0 → 3.8.0

package/scripts/hooks/stop-goal-fit.js

@@ -1759,6 +1759,37 @@ function hasSidecarPresence(artifactDir) {
   return fs.existsSync(path.join(artifactDir, 'state.json')) || fs.existsSync(path.join(artifactDir, 'trust.bundle'));
 }
 
+function canonicalFlowState(root, artifactDir) {
+  if (!artifactDir) return { state: null, error: null };
+  const slug = path.basename(artifactDir);
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug)) return { state: null, error: 'canonical Flow run slug is malformed' };
+  const runDir = path.join(root, '.kontourai', 'flow', 'runs', slug);
+  const components = [
+    path.join(root, '.kontourai'),
+    path.join(root, '.kontourai', 'flow'),
+    path.join(root, '.kontourai', 'flow', 'runs'),
+    runDir,
+  ];
+  try {
+    for (const component of components) {
+      const stat = fs.lstatSync(component);
+      if (stat.isSymbolicLink() || !stat.isDirectory()) return { state: null, error: `canonical Flow run has an unsafe parent component: ${component}` };
+    }
+    const file = path.join(runDir, 'state.json');
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink() || !stat.isFile()) return { state: null, error: 'canonical Flow state must be a non-symlink regular file' };
+    const state = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!state || typeof state !== 'object' || Array.isArray(state)
+      || typeof state.status !== 'string' || !state.status.trim()
+      || typeof state.current_step !== 'string' || !state.current_step.trim()) {
+      return { state: null, error: 'canonical Flow state is malformed' };
+    }
+    return { state, error: null };
+  } catch (error) {
+    return { state: null, error: `canonical Flow state is unavailable or malformed: ${safeOneLine(error && error.message || error, 120)}` };
+  }
+}
+
 // WS8 (AC10a): when current.json names a slug whose session directory does NOT exist,
 // return that slug so analyze() can log the staleness rather than silently falling back to
 // a global mtime scan that could resurface an abandoned/never-real session as active.
@@ -1871,7 +1902,7 @@ function missingBundleOrStateSignal(artifactDir, activeFlowStep) {
 //
 // Both are used in analyze() for blocking decisions AND in run() for the AC2
 // MAX_BLOCKS hard-block guard (preventing auto-release of hard blocks).
-const HARD_BLOCK = /contradicts evidence\.json|caught false-completion|evidence verdict:|evidence check .+ status:|critique status|critique open|required sidecar is missing|command-log integrity check FAILED|gate misconfiguration:|exit-code-laundered|NOT_VERIFIED \(ambiguous\)/;
+const HARD_BLOCK = /contradicts evidence\.json|caught false-completion|evidence verdict:|evidence check .+ status:|critique status|critique open|required sidecar is missing|command-log integrity check FAILED|gate misconfiguration:|exit-code-laundered|NOT_VERIFIED \(ambiguous\)|canonical Flow (?:run remains active|state is unsafe or malformed)/;
 // FULL_BLOCK adds: workflow-state hygiene, surface-unavailable fail-closed, missing log.
 const FULL_BLOCK = /status:|Definition Of Done|Goal Fit|sidecar validation:|contradicts evidence\.json|workflow state|evidence verdict|evidence check|NOT_VERIFIED gap|critique status|critique open|next action|caught false-completion|NOT_VERIFIED —|command-log integrity check FAILED|gate misconfiguration:|surface unavailable —|expected capture log is missing|exit-code-laundered|malformed-evidence|NOT_VERIFIED \(ambiguous\)/;
 
@@ -1897,7 +1928,31 @@ async function analyze(root, now = Date.now()) {
     artifacts = artifacts.filter(a => a && hasSidecarPresence(path.dirname(a.file)));
   }
 
-  if (artifacts.length === 0) return { warnings: [], blocking: false, latestArtifactDir: null };
+  const scopedCanonicalFlow = canonicalFlowState(root, scoped);
+  const scopedState = scoped ? readJsonFile(path.join(scoped, 'state.json')) : null;
+  const scopedProjectedActive = Boolean(scopedState && scopedState.flow_run && normalizedStatus(scopedState.flow_run.status) === 'active');
+  if (scopedProjectedActive && scopedCanonicalFlow.error) {
+    return {
+      warnings: [`workflow state: canonical Flow state is unsafe or malformed for the active scoped session: ${scopedCanonicalFlow.error}. Resolve the canonical run before stopping.`],
+      blocking: true,
+      activeFlowRun: true,
+      latestArtifactDir: scoped,
+      gatePrefix: '[stop-gate]',
+    };
+  }
+  if (artifacts.length === 0) {
+    if (normalizedStatus(scopedCanonicalFlow.state?.status) === 'active') {
+      const activeStep = safeOneLine(scopedCanonicalFlow.state.current_step || 'unknown', 80);
+      return {
+        warnings: [`workflow state: canonical Flow run remains active at step ${activeStep}; complete or explicitly cancel the run before stopping.`],
+        blocking: true,
+        activeFlowRun: true,
+        latestArtifactDir: scoped,
+        gatePrefix: '[stop-gate]',
+      };
+    }
+    return { warnings: [], blocking: false, activeFlowRun: false, latestArtifactDir: null };
+  }
 
   const latest = artifacts[0];
   const latestArtifactDir = path.dirname(latest.file);
@@ -1965,14 +2020,25 @@ async function analyze(root, now = Date.now()) {
   // Use module-scope HARD_BLOCK / FULL_BLOCK (defined above analyze()).
   // pre-execution/terminal tasks: only HARD_BLOCK signals cause a block.
   // execution-onward tasks: FULL_BLOCK signals cause a block.
-  const activeFlowRun = gateState && gateState.flow_run && normalizedStatus(gateState.flow_run.status) === 'active';
+  const canonicalFlow = canonicalFlowState(root, latestArtifactDir);
+  const activeProjectedFlow = gateState && gateState.flow_run && normalizedStatus(gateState.flow_run.status) === 'active';
+  const unsafeActiveCanonical = Boolean(activeProjectedFlow && canonicalFlow.error);
+  if (unsafeActiveCanonical) {
+    warnings.push(`workflow state: canonical Flow state is unsafe or malformed for the active scoped session: ${canonicalFlow.error}. Resolve the canonical run before stopping.`);
+  }
+  const activeFlowRun = normalizedStatus(canonicalFlow.state?.status) === 'active'
+    || (gateState && gateState.flow_run && normalizedStatus(gateState.flow_run.status) === 'active');
+  if (activeFlowRun && !warnings.some(w => /canonical Flow run remains active/.test(w))) {
+    const activeStep = safeOneLine(canonicalFlow.state?.current_step || gateState?.flow_run?.current_step || 'unknown', 80);
+    warnings.push(`workflow state: canonical Flow run remains active at step ${activeStep}; complete or explicitly cancel the run before stopping.`);
+  }
   const blockRe = ((preExecution && !activeFlowRun) || terminal) ? HARD_BLOCK : FULL_BLOCK;
-  const blocking = warnings.some(w => {
+  const blocking = activeFlowRun || warnings.some(w => {
     // Capture cross-reference warn-mode notes never block (operator opted out).
     if (/\[backstop in warn mode — not blocking\]/.test(w)) return false;
     return blockRe.test(w);
   });
-  return { warnings, blocking, preExecution, gatePrefix: gateLabel(activeFlowStep), latestArtifactDir };
+  return { warnings, blocking, activeFlowRun, preExecution, gatePrefix: gateLabel(activeFlowStep), latestArtifactDir };
 }
 
 /**
@@ -2220,8 +2286,9 @@ function releaseOnNonTerminalStop(root, artifactDir) {
 
     const state = readJsonFile(path.join(artifactDir, 'state.json'));
     if (!state) return; // AC5: no state.json — nothing to gate a release decision on.
-    if (state.flow_run && normalizedStatus(state.flow_run.status) === 'active') {
-      process.stderr.write(`[Hook] Goal Fit: stop-hook release skipped for active Flow run "${safeOneLine(state.flow_run.run_id || state.task_slug || 'unknown', 80)}"; continuation remains governed by Flow state.\n`);
+    const canonicalFlow = canonicalFlowState(root, artifactDir);
+    if (normalizedStatus(canonicalFlow.state?.status) === 'active' || (state.flow_run && normalizedStatus(state.flow_run.status) === 'active')) {
+      process.stderr.write(`[Hook] Goal Fit: stop-hook release skipped for active Flow run "${safeOneLine(state.flow_run?.run_id || state.task_slug || path.basename(artifactDir), 80)}"; continuation remains governed by Flow state.\n`);
       return;
     }
 
@@ -2367,7 +2434,7 @@ async function run(rawInput) {
     // with runtime-constructed paths or by modifying the warning
     // text so the hash changes. The real anchor is external (signed checkpoints + human
     // review). This raises the cost of the burn-through-the-counter escape vector.
-    const isHardBlock = result.warnings.some(w => {
+    const isHardBlock = result.activeFlowRun || result.warnings.some(w => {
       if (/\[backstop in warn mode — not blocking\]/.test(w)) return false;
       return HARD_BLOCK.test(w);
     });
@@ -2375,7 +2442,9 @@ async function run(rawInput) {
       // Do NOT clear the streak — keep accumulating so the same hard block stays visible.
       return {
         stdout: rawInput,
-        stderr: `${message}\n${gatePrefix} max-blocks reached but the block is a caught false-completion / integrity failure — not auto-releasing; requires a real fix or operator override.`,
+        stderr: result.activeFlowRun
+          ? `${message}\n${gatePrefix} max-blocks reached but canonical Flow remains active — not auto-releasing; complete or explicitly cancel the run.`
+          : `${message}\n${gatePrefix} max-blocks reached but the block is a caught false-completion / integrity failure — not auto-releasing; requires a real fix or operator override.`,
         exitCode: 2,
       };
     }

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);