@piagent/platform 1.2.17 → 1.3.0-ie.9

package/packages/piagent-core/extensions/policy-core.js

@@ -1,9 +1,8 @@
+import { excludedFindSelectorValue, findSelectorOption, SEARCH_COMMANDS, SEARCH_FILE_OPTIONS, SEARCH_GLOB_OPTIONS,
+  SEARCH_PATTERN_OPTIONS, searchSelectorIsExclusion, searchSelectorWithinToken } from "./shell-selector-policy.js";
+
 const PATH_REDIRECT_OPERATORS = new Set(["<", ">", ">>", "1>", "1>>", "2>", "2>>", "&>", "&>>"]);
 const DATA_ONLY_COMMANDS = new Set(["echo", "printf"]);
-const SEARCH_COMMANDS = new Set(["grep", "egrep", "fgrep", "rg", "ripgrep"]);
-const SEARCH_FILE_OPTIONS = new Set(["-f", "--file", "--exclude-from", "--ignore-file"]);
-const SEARCH_GLOB_OPTIONS = new Set(["-g", "--glob", "--iglob", "--include", "--exclude"]);
-const SEARCH_PATTERN_OPTIONS = new Set(["-e", "--regexp", "--pattern"]);
 const ASSIGNMENT_BUILTINS = new Set(["export", "readonly", "declare", "typeset", "local"]);
 const SHELL_COMMANDS = new Set(["bash", "sh", "zsh"]);
 
@@ -46,9 +45,7 @@ export function normalizePathCandidate(candidate) {
   if (typeof candidate !== "string") return "";
   const raw = candidate.trim().replace(/^['"]|['"]$/g, "");
   if (/^\/+$/.test(raw)) return "/";
-  return candidate
-    .trim()
-    .replace(/^['"]|['"]$/g, "")
+  return raw
     .replace(/\\/g, "/")
     .replace(/^\.\//, "")
     .replace(/\/+/g, "/")
@@ -520,7 +517,7 @@ function expandShellBraces(word, mask = "0".repeat(word.length), depth = 0) {
  * @param {{value: string, literalMask?: string}} redirect
  * @returns {{value: string, mask: string}[]}
  */
-function redirectionTargetWords(redirect) {
+export function redirectionTargetWords(redirect) {
   // The scanner writes one mask character per target character, so the fallback
   // is a defensive default rather than a reachable branch. Unmasked is the safe
   // direction of the two: it expands, and expanding offers more to check.
@@ -1229,11 +1226,22 @@ export function evaluateExecPolicyCore(command, options) {
     segments.push({ command: segment, expanded: text, words, matches, warnings });
   }
 
-  // The expanded text of every segment as well as the raw command, so a pattern
-  // written as `git push` still matches when the author typed `git p{ush,}`.
-  const normalizedCommand = [command, ...segments.map((entry) => entry.expanded)].join("\n").toLowerCase();
+  const confirmationPatternMatches = (pattern, words) => {
+    const expected = shellWords(String(pattern ?? ""));
+    if (expected.length === 0) return false;
+    const executableWords = stripWrapper(words);
+    if (arrayStartsWith(executableWords, expected)) return true;
+    if (expected.length !== 1) return false;
+    const action = expected[0];
+    const executable = commandBasename(executableWords[0] ?? "");
+    if (["npm", "pnpm", "yarn", "bun"].includes(executable)) {
+      const args = executableWords.slice(1).filter((word) => !word.startsWith("-"));
+      return args[0] === action || (args[0] === "run" && args[1] === action);
+    }
+    return ["just", "make", "task"].includes(executable) && executableWords.slice(1).some((word) => word === action);
+  };
   for (const pattern of policy.requireConfirmationPatterns ?? []) {
-    if (normalizedCommand.includes(String(pattern).toLowerCase())) {
+    if (segments.some((entry) => confirmationPatternMatches(pattern, entry.words))) {
       reasons.push(`Confirmation required by legacy policy pattern: ${pattern}`);
       break;
     }
@@ -1942,7 +1950,7 @@ function xargsPipelineInputCandidates(command) {
   return candidates;
 }
 
-function extractAttachedRedirectionPaths(segment) {
+export function extractAttachedRedirectionPaths(segment) {
   const paths = [];
   let quote;
   let escaped = false;
@@ -2062,15 +2070,6 @@ function extractAttachedRedirectionPaths(segment) {
   return paths;
 }
 
-export function shellHasFileWriteRedirection(command) {
-  return splitShellSegments(String(command ?? "")).some((segment) => (
-    extractAttachedRedirectionPaths(segment)
-      .filter((redirect) => redirect.writesFile)
-      .flatMap(redirectionTargetWords)
-      .length > 0
-  ));
-}
-
 export function extractShellPathCandidates(command) {
   const candidates = [...xargsPipelineInputCandidates(command)];
   const assignments = new Map();
@@ -2094,12 +2093,12 @@ export function extractShellPathCandidates(command) {
       .map((entry) => entry.value)
       .filter((word) => word !== expanded));
   };
-  const pending = splitShellSegments(command).map((segment) => ({ segment, depth: 0 }));
+  const rootSegments = splitShellSegments(command);
+  const pending = rootSegments.map((segment, index) => ({ segment, depth: 0, piped: rootSegments[index + 1] !== undefined && feedsFileOperandConsumer(rootSegments[index + 1], assignments) }));
   while (pending.length > 0) {
-    const { segment, depth } = pending.shift();
-    // One stream for the command name and for the operands alike: `{cat,.env}`
-    // is a `cat` whose only argument came out of the same word, and reading the
-    // name from one list and the arguments from another lost it.
+    const { segment, depth, piped } = pending.shift();
+    // One stream for command and operands: `{cat,.env}` expands to a `cat` whose
+    // argument must not be lost by reading its command from a different list.
     const { words, text, tokens, braceText, evaluable } = expandedSegment(segment, assignments);
     const expandedWords = words;
     rememberLeadingShellAssignments(words, assignments);
@@ -2164,6 +2163,7 @@ export function extractShellPathCandidates(command) {
           if (pathPart) addCandidate(pathPart, argumentTokens[index].variableActive, argumentTokens[index].braceActive);
           continue;
         }
+        if (excludedFindSelectorValue(argumentTokens, index, commandName, piped)) continue;
         const optionEquals = word.indexOf("=");
         const optionName = optionEquals > 0 ? word.slice(0, optionEquals) : word;
         const inlineOptionValue = optionEquals > 0 ? word.slice(optionEquals + 1) : undefined;
@@ -2191,17 +2191,16 @@ export function extractShellPathCandidates(command) {
           continue;
         }
         if (attachedRgOption?.option === "-g") {
-          addCandidate(attachedRgOption.value, argumentTokens[index].variableActive, argumentTokens[index].braceActive);
+          const selector = argumentTokens[index].variableActive ? expandKnownShellVariables(attachedRgOption.value, assignments) : attachedRgOption.value;
+          if (!searchSelectorIsExclusion(commandName, "-g", selector)) addCandidate(attachedRgOption.value, argumentTokens[index].variableActive, argumentTokens[index].braceActive);
           continue;
         }
         if (SEARCH_COMMANDS.has(commandName) && (SEARCH_FILE_OPTIONS.has(optionName) || SEARCH_GLOB_OPTIONS.has(optionName))) {
-          if (inlineOptionValue !== undefined) {
-            addCandidate(inlineOptionValue, argumentTokens[index].variableActive, argumentTokens[index].braceActive);
-          } else {
-            const target = argumentTokens[index + 1];
-            if (target) addCandidate(target.value, target.variableActive, target.braceActive);
-            index += 1;
-          }
+          const target = inlineOptionValue === undefined ? argumentTokens[index + 1] : argumentTokens[index];
+          const targetValue = inlineOptionValue ?? target?.value;
+          const selector = target?.variableActive && targetValue !== undefined ? expandKnownShellVariables(targetValue, assignments) : targetValue;
+          if (targetValue !== undefined && !searchSelectorIsExclusion(commandName, optionName, selector)) addCandidate(targetValue, target?.variableActive, target?.braceActive);
+          if (inlineOptionValue === undefined) index += 1;
           if (SEARCH_FILE_OPTIONS.has(optionName) && (optionName === "-f" || optionName === "--file")) searchPatternPending = false;
           continue;
         }
@@ -2225,18 +2224,18 @@ export function extractShellPathCandidates(command) {
     }
     if (depth < MAX_NESTED_DEPTH) {
       for (const nestedCommand of extractNestedCommands(braceText, expandedWords)) {
-        for (const nestedSegment of splitShellSegments(nestedCommand)) {
+        const nestedSegments = splitShellSegments(nestedCommand);
+        for (const [nestedSegmentIndex, nestedSegment] of nestedSegments.entries()) {
           // `$(echo -e '.en\x76')` prints `.env`, and `printf` decodes its
           // format the same way. The backslash is gone by the time the body is
           // tokenized, so the escape is read back off the raw text -- the same
           // reading the `xargs` producer already gets.
-          const nestedWords = shellWords(nestedSegment);
-          const nestedName = commandBasename(stripWrapper(expandedSegment(nestedSegment, assignments).words)[0] ?? "");
+          const nestedWords = shellWords(nestedSegment); const nestedName = commandBasename(stripWrapper(expandedSegment(nestedSegment, assignments).words)[0] ?? "");
           const nestedIndex = producerCommandIndex(nestedWords, nestedName);
           if (nestedName === "printf" || (nestedName === "echo" && echoEscapeMode(nestedWords, nestedIndex))) {
             for (const literal of escapedLiteralCandidates(nestedSegment)) addCandidate(literal, false);
           }
-          pending.push({ segment: nestedSegment, depth: depth + 1 });
+          pending.push({ segment: nestedSegment, depth: depth + 1, piped: nestedSegments[nestedSegmentIndex + 1] !== undefined && feedsFileOperandConsumer(nestedSegments[nestedSegmentIndex + 1], assignments) });
         }
       }
     }
@@ -2312,6 +2311,7 @@ export function extractShellGlobCandidates(command) {
           index += 1;
           continue;
         }
+        if (excludedFindSelectorValue(argumentTokens, index, commandName, piped)) continue;
         const optionEquals = token.value.indexOf("=");
         const optionName = optionEquals > 0 ? token.value.slice(0, optionEquals) : token.value;
         const inlineOptionValue = optionEquals > 0 ? token.value.slice(optionEquals + 1) : undefined;
@@ -2333,7 +2333,7 @@ export function extractShellGlobCandidates(command) {
           const expanded = token.variableActive
             ? expandKnownShellVariables(attachedRgOption.value, assignments)
             : attachedRgOption.value;
-          candidates.push(expanded);
+          if (!searchSelectorIsExclusion(commandName, "-g", expanded)) candidates.push(expanded);
           continue;
         }
         if (SEARCH_COMMANDS.has(commandName) && (SEARCH_FILE_OPTIONS.has(optionName) || SEARCH_GLOB_OPTIONS.has(optionName))) {
@@ -2342,7 +2342,8 @@ export function extractShellGlobCandidates(command) {
           if (targetValue !== undefined) {
             const targetVariableActive = inlineOptionValue === undefined ? target?.variableActive : token.variableActive;
             const expanded = targetVariableActive ? expandKnownShellVariables(targetValue, assignments) : targetValue;
-            if (SEARCH_GLOB_OPTIONS.has(optionName) || target?.activeGlob || (target?.unquotedVariable && /[*?{\[]/.test(expanded))) {
+            if (!searchSelectorIsExclusion(commandName, optionName, expanded)
+              && (SEARCH_GLOB_OPTIONS.has(optionName) || target?.activeGlob || (target?.unquotedVariable && /[*?{\[]/.test(expanded)))) {
               candidates.push(expanded);
             }
           }
@@ -2512,42 +2513,41 @@ export function unresolvedPathExpansions(command) {
       const argumentTokens = executableArgumentTokens(tokens, words, commandName);
       for (let index = 0; index < argumentTokens.length; index += 1) {
         const token = argumentTokens[index];
+        if (excludedFindSelectorValue(argumentTokens, index, commandName, piped)) continue;
+        const attachedRgOption = ["rg", "ripgrep"].includes(commandName) ? attachedRgShortOption(token.value) : undefined;
+        const embeddedSelector = searchSelectorWithinToken(commandName, token.value, attachedRgOption);
+        if (token.variableActive && embeddedSelector) {
+          const expanded = expandKnownShellVariables(embeddedSelector.value, assignments);
+          if (/\$\{|\$\(|`|\$[A-Za-z_]/.test(expanded)) unresolved.push(token.value);
+          continue;
+        }
+        const previousOption = argumentTokens[index - 1]?.value ?? "";
+        const expandedToken = token.variableActive ? expandKnownShellVariables(token.value, assignments) : token.value;
+        if (searchSelectorIsExclusion(commandName, previousOption, expandedToken)) {
+          if (token.variableActive && /\$\{|\$\(|`|\$[A-Za-z_]/.test(expandedToken)) unresolved.push(token.value);
+          continue;
+        }
+        if (SEARCH_COMMANDS.has(commandName) && SEARCH_PATTERN_OPTIONS.has(previousOption)) continue;
         if (!token.variableActive) continue;
         if (token.value.startsWith("-")) continue;
-        // `grep`'s first bare operand is the pattern, so the command does not
-        // open files by name -- but the word after `-f` does, and
-        // `grep -f ${X:+.env} README.md` reads a protected file with the
-        // command sitting outside every list that says so.
-        const namedByFlag = SEARCH_COMMANDS.has(commandName)
-          && SEARCH_FILE_OPTIONS.has(argumentTokens[index - 1]?.value ?? "");
-        // `dd if=.en$(echo v)` hides a filename in an operand value. Reading the
-        // key as literal text would refuse every `TAG=build$(date +%s)` too, so
-        // the value is taken on its own and only when it is shaped like a path.
+        // Bare grep operands start with a pattern, but values of file/glob flags
+        // and find selectors are paths or selectors whose expansion must resolve.
+        const namedByFlag = (SEARCH_COMMANDS.has(commandName) && (SEARCH_FILE_OPTIONS.has(previousOption) || SEARCH_GLOB_OPTIONS.has(previousOption)))
+          || (commandName === "find" && findSelectorOption(previousOption));
+        // Inspect only the path-shaped value in operands such as `dd if=.en$V`;
+        // treating every `KEY=value` as a path would refuse ordinary metadata.
         const operandValue = operandValuePath(token.value);
         const word = operandValue ?? token.value;
-        if (operandValue !== undefined
-          && !operandValue.includes("/")
-          && !operandValue.startsWith(".")) continue;
+        if (operandValue !== undefined && !operandValue.includes("/") && !operandValue.startsWith(".")) continue;
         if (word.startsWith("-")) continue;
-        const expanded = expandKnownShellVariables(word, assignments);
+        const expanded = operandValue === undefined ? expandedToken : expandKnownShellVariables(word, assignments);
         const basename = expanded.slice(expanded.lastIndexOf("/") + 1);
-        // A name assembled out of pieces is a filename wherever it appears. A
-        // word that is *nothing but* one parameter expansion is a filename only
-        // where the command says so -- and there it is refused too, because the
-        // whole point of this net is that a form nobody has modelled yet should
-        // cost a question rather than a miss. Widening it to every command would
-        // ask about `git commit -m $MSG`. Words printed into an `xargs cat` are
-        // operands of that `cat`, whatever printed them. And a name nobody can
-        // evaluate could be a command that opens files: `${X:+cat} ${X:+.env}`
-        // reads a protected file whenever the variable is set, and both halves
-        // read as words naming nothing. This only fires when the operand is
-        // unresolved too, so a named command with a literal operand is untouched.
-        const opensFiles = FILE_OPERAND_COMMANDS.has(commandName)
-          || piped
-          || namedByFlag
+        // Piecewise names always fail closed. A bare expansion does so only in a
+        // known file/selector position, an xargs file pipeline, or a dynamic command.
+        const opensFiles = FILE_OPERAND_COMMANDS.has(commandName) || piped || namedByFlag
           || commandNameIsDynamic(commandName);
         const bare = opensFiles && holdsUnresolvedParameter(basename);
-        if (assemblesFilename(basename) || bare) unresolved.push(token.value);
+        if ((namedByFlag && /\$\{|\$\(|`|\$[A-Za-z_]/.test(expanded)) || assemblesFilename(basename) || bare) unresolved.push(token.value);
       }
     }
     if (depth < MAX_NESTED_DEPTH) {

package/packages/piagent-core/extensions/repository-memory.js

@@ -0,0 +1,189 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { redactForStorage } from "./redaction-core.js";
+import { appendJsonlBounded, readJsonlTail } from "./state-retention.js";
+import { ensurePrivateStateDirectory, resolveLocalStatePath } from "./local-state-path.js";
+import { matchesProtectedPath } from "./policy-core.js";
+import { isCurrentWorkingTreeDigest } from "./working-tree-digest.js";
+
+const MEMORY_SCHEMA_VERSION = 1;
+const MAX_FACT_CHARS = 1_000;
+const MAX_REASON_CHARS = 400;
+const MAX_EVENTS_BYTES = 2 * 1024 * 1024;
+const RESTRICTED_MEMORY_MATERIAL = /\b(raw prompt|raw output|transcript|oauth(?: token)?|api[ _-]?key|access token|refresh token|secret)\b/i;
+const SEARCH_STOP_WORDS = new Set(["about", "after", "before", "change", "check", "from", "into", "please", "task", "that", "the", "this", "with"]);
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function factIdentity(normalized) {
+  const { expiresAt: _expiresAt, ...durableFact } = normalized;
+  return sha256(JSON.stringify(durableFact)).slice(0, 16);
+}
+
+function memoryPaths(cwd) {
+  const root = path.join(cwd, ".pi", "piagent-state", "repository-memory");
+  return {
+    root,
+    facts: path.join(root, "facts.jsonl")
+  };
+}
+
+function normalizePath(value) {
+  return String(value ?? "").replaceAll("\\", "/").replace(/^\.\/+/, "").trim();
+}
+
+function validCitation(citation) {
+  const sourcePath = normalizePath(citation?.path);
+  return sourcePath
+    && !sourcePath.startsWith("../")
+    && !path.isAbsolute(sourcePath)
+    && typeof citation?.reason === "string"
+    && citation.reason.trim().length > 0;
+}
+
+function assertSafeMemoryText(label, value) {
+  if (RESTRICTED_MEMORY_MATERIAL.test(String(value ?? ""))) {
+    throw new Error(`Repository memory ${label} must not store raw prompts, outputs, OAuth material, or secrets`);
+  }
+}
+
+function normalizeFact(input) {
+  const fact = String(input?.fact ?? "").trim();
+  const reason = String(input?.reason ?? "").trim();
+  const citations = Array.isArray(input?.citations) ? input.citations.filter(validCitation).slice(0, 8).map((citation) => ({
+    path: normalizePath(citation.path),
+    reason: String(citation.reason).trim().slice(0, MAX_REASON_CHARS),
+    digest: isCurrentWorkingTreeDigest(citation.digest)
+      ? citation.digest
+      : undefined
+  })) : [];
+  if (fact.length < 8 || fact.length > MAX_FACT_CHARS) throw new Error(`Repository memory fact must be 8-${MAX_FACT_CHARS} chars`);
+  if (!["fact", "decision", "retrieval-feedback"].includes(input?.kind)) throw new Error("Repository memory kind is invalid");
+  if (!reason || reason.length > MAX_REASON_CHARS) throw new Error(`Repository memory reason must be 1-${MAX_REASON_CHARS} chars`);
+  if (citations.length === 0) throw new Error("Repository memory requires at least one path citation");
+  assertSafeMemoryText("fact", fact);
+  assertSafeMemoryText("reason", reason);
+  for (const citation of citations) assertSafeMemoryText("citation reason", citation.reason);
+  const expiresAt = typeof input?.expiresAt === "string" && Number.isFinite(Date.parse(input.expiresAt))
+    ? input.expiresAt
+    : undefined;
+  return {
+    schemaVersion: MEMORY_SCHEMA_VERSION,
+    kind: input.kind,
+    fact,
+    reason,
+    confidence: ["low", "medium", "high"].includes(input.confidence) ? input.confidence : "medium",
+    citations,
+    expiresAt
+  };
+}
+
+export function appendRepositoryMemoryFact(cwd, input, options = {}) {
+  const normalized = normalizeFact(input);
+  const paths = memoryPaths(cwd);
+  ensurePrivateStateDirectory(cwd, paths.root, "Repository memory root");
+  const record = {
+    ...normalized,
+    id: factIdentity(normalized),
+    recordedAt: typeof options.recordedAt === "string" && Number.isFinite(Date.parse(options.recordedAt))
+      ? options.recordedAt
+      : nowIso()
+  };
+  appendJsonlBounded(paths.facts, redactForStorage(record), {
+    maxBytes: MAX_EVENTS_BYTES,
+    mode: 0o600,
+    projectRoot: cwd
+  });
+  return record;
+}
+
+export function recordCompletedTaskMemory(cwd, task, options = {}) {
+  const citations = (Array.isArray(task?.changedFiles) ? task.changedFiles : []).slice(0, 8).map((file) => ({
+    path: file,
+    reason: "Changed file verified by the task completion gate.",
+    digest: task?.finalFileDigests?.[file]
+  }));
+  if (citations.length === 0) return undefined;
+  const nowMs = Number.isFinite(options.nowMs) ? options.nowMs : Date.now();
+  return appendRepositoryMemoryFact(cwd, {
+    kind: "retrieval-feedback",
+    fact: `Verified source changes completed for ${citations.length} cited file(s).`,
+    reason: "Derived from a completed task contract and current-tree verification evidence.",
+    confidence: "high",
+    citations,
+    expiresAt: new Date(nowMs + 90 * 24 * 60 * 60 * 1000).toISOString()
+  }, { recordedAt: options.recordedAt });
+}
+
+export function readRepositoryMemoryFacts(cwd, options = {}) {
+  const paths = memoryPaths(cwd);
+  let safePath;
+  try {
+    safePath = resolveLocalStatePath(cwd, paths.facts, { label: "Repository memory facts" });
+  } catch {
+    return [];
+  }
+  if (options.limit === 0) return [];
+  const parsedNow = options.now ? Date.parse(options.now) : Date.now();
+  const now = Number.isFinite(parsedNow) ? parsedNow : Date.now();
+  const rows = readJsonlTail(safePath, {
+    limit: Number.isInteger(options.limit) ? Math.max(1, options.limit) : 200,
+    maxBytes: MAX_EVENTS_BYTES,
+    projectRoot: cwd
+  });
+  const byId = new Map();
+  for (const row of rows) {
+    try {
+      const normalized = normalizeFact(row);
+      if (row.expiresAt && Date.parse(row.expiresAt) <= now) continue;
+      byId.set(row.id ?? factIdentity(normalized), {
+        ...normalized,
+        id: row.id,
+        recordedAt: row.recordedAt
+      });
+    } catch {
+      // Ignore malformed rows; the source of truth remains repository files.
+    }
+  }
+  return [...byId.values()].sort((left, right) => Date.parse(right.recordedAt ?? 0) - Date.parse(left.recordedAt ?? 0));
+}
+
+function memorySearchTerms(value) {
+  return [...new Set(String(value ?? "")
+    .toLowerCase()
+    .match(/[a-z][a-z0-9_.:/-]{2,63}/g) ?? [])]
+    .filter((term) => !SEARCH_STOP_WORDS.has(term));
+}
+
+export function selectRepositoryMemoryFacts(cwd, query, options = {}) {
+  if (!Array.isArray(options.excludePatterns)) {
+    throw new Error("selectRepositoryMemoryFacts requires an explicit excludePatterns array");
+  }
+  const terms = memorySearchTerms(query);
+  if (terms.length === 0) return [];
+  const limit = Number.isInteger(options.limit) ? Math.max(0, Math.min(8, options.limit)) : 3;
+  if (limit === 0) return [];
+  return readRepositoryMemoryFacts(cwd, { limit: 200, now: options.now })
+    .filter((record) => record.citations.every((citation) => !matchesProtectedPath(citation.path, options.excludePatterns)))
+    .map((record) => {
+      const searchable = [
+        record.fact,
+        record.reason,
+        ...record.citations.flatMap((citation) => [citation.path, citation.reason])
+      ].join(" ").toLowerCase();
+      const matchedTerms = terms.filter((term) => searchable.includes(term));
+      const confidenceWeight = record.confidence === "high" ? 2 : record.confidence === "medium" ? 1 : 0;
+      return { record, score: matchedTerms.length * 10 + confidenceWeight, matchedTerms };
+    })
+    .filter((candidate) => candidate.matchedTerms.length > 0)
+    .sort((left, right) => right.score - left.score || Date.parse(right.record.recordedAt ?? 0) - Date.parse(left.record.recordedAt ?? 0))
+    .slice(0, limit);
+}

package/packages/piagent-core/extensions/return-contract.js

@@ -0,0 +1,130 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+import { normalizePathCandidate } from "./policy-core.js";
+
+const MAX_FILE_BYTES = 256 * 1024;
+
+function normalizedText(value) {
+  return String(value ?? "")
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase();
+}
+
+function escapeRegex(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function uniqueStrings(values) {
+  return [...new Set(values.filter((item) => typeof item === "string" && item.trim()).map((item) => item.trim()))];
+}
+
+function readTextIfSmall(cwd, file) {
+  try {
+    const target = path.resolve(cwd, file);
+    const relative = path.relative(cwd, target);
+    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return "";
+    const stat = fs.statSync(target);
+    if (!stat.isFile() || stat.size > MAX_FILE_BYTES) return "";
+    return fs.readFileSync(target, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function gitBaselineText(cwd, file) {
+  const normalized = normalizePathCandidate(file);
+  if (!normalized || normalized.startsWith("../") || path.isAbsolute(normalized)) return "";
+  try {
+    const text = execFileSync("git", ["-C", cwd, "show", `HEAD:${normalized}`], {
+      encoding: "utf8",
+      maxBuffer: MAX_FILE_BYTES + 1,
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 2_000
+    });
+    return Buffer.byteLength(text, "utf8") <= MAX_FILE_BYTES ? text : "";
+  } catch {
+    return "";
+  }
+}
+
+function matchingBrace(text, opening) {
+  let depth = 0;
+  for (let index = opening; index < text.length; index += 1) {
+    if (text[index] === "{") depth += 1;
+    else if (text[index] === "}" && --depth === 0) return index;
+  }
+  return -1;
+}
+
+function helperParameterComesFromProperty(text, resultVariable, identifier) {
+  const declarations = /\bfunction\s+([a-z_$][a-z0-9_$]*)\s*\(([^)]*)\)\s*\{/g;
+  for (const declaration of text.matchAll(declarations)) {
+    const parameters = declaration[2].split(",").map((value) => value.trim());
+    if (!parameters.includes(identifier)) continue;
+    const opening = declaration.index + declaration[0].lastIndexOf("{");
+    const closing = matchingBrace(text, opening);
+    if (closing < 0) continue;
+    const body = text.slice(opening + 1, closing);
+    const pushesParameter = new RegExp(`\\b${escapeRegex(resultVariable)}\\.push\\s*\\(\\s*${escapeRegex(identifier)}\\s*\\)`).test(body);
+    if (!pushesParameter) continue;
+    const outside = `${text.slice(0, declaration.index)} ${text.slice(closing + 1)}`;
+    const propertySeed = new RegExp(`\\b${escapeRegex(declaration[1])}\\s*\\(\\s*[a-z_$][a-z0-9_$]*\\.[a-z_$][a-z0-9_$]*\\s*\\)`).test(outside);
+    if (propertySeed) return true;
+  }
+  return false;
+}
+
+export function returnedElementRepresentation(sourceText) {
+  const text = normalizedText(sourceText);
+  const returnedVariables = uniqueStrings([...text.matchAll(/\breturn\s+([a-z_$][a-z0-9_$]*)\s*;?/g)].map((match) => match[1]));
+  const objectValuedMaps = new Set();
+  const objectMapPattern = /\b(?:const|let|var)\s+([a-z_$][a-z0-9_$]*)\s*=\s*new\s+map\s*\(\s*[a-z_$][a-z0-9_$]*\.map\s*\(\s*\(?\s*([a-z_$][a-z0-9_$]*)\s*\)?\s*=>\s*\[\s*\2\.[a-z_$][a-z0-9_$]*\s*,\s*\2\s*\]\s*\)\s*\)/g;
+  for (const match of text.matchAll(objectMapPattern)) objectValuedMaps.add(match[1]);
+  const kinds = new Set();
+  for (const variable of returnedVariables) {
+    const pushPattern = new RegExp(`\\b${escapeRegex(variable)}\\.push\\s*\\(\\s*([^);\\n]{1,240})`, "g");
+    for (const match of text.matchAll(pushPattern)) {
+      const expression = match[1].trim();
+      if ([...objectValuedMaps].some((mapName) => new RegExp(`^${escapeRegex(mapName)}\\.get\\s*\\(`).test(expression))) kinds.add("object");
+      else if (/^[a-z_$][a-z0-9_$]*\.[a-z_$][a-z0-9_$]*\b/.test(expression)) kinds.add("name");
+      else if (/^(?:[a-z_$][a-z0-9_$]*\s*\[|\{)/.test(expression)) kinds.add("object");
+      else if (/^[a-z_$][a-z0-9_$]*$/.test(expression) && helperParameterComesFromProperty(text, variable, expression)) kinds.add("name");
+    }
+  }
+  if (/\breturn\s+[a-z_$][a-z0-9_$]*\.map\s*\([^)]*=>\s*[a-z_$][a-z0-9_$]*\.[a-z_$][a-z0-9_$]*\b/.test(text)) kinds.add("name");
+  if (/\breturn\s+[a-z_$][a-z0-9_$]*\.map\s*\([^)]*=>\s*[a-z_$][a-z0-9_$]*\s*\)/.test(text)) kinds.add("object");
+  return kinds.size === 1 ? [...kinds][0] : undefined;
+}
+
+function explicitlyChangesReturnRepresentation(taskText) {
+  return /\b(?:change|replace)\b[^.\n]{0,80}\breturn (?:shape|representation)\b/.test(normalizedText(taskText));
+}
+
+export function baselineReturnRepresentationConflicts(taskText, cwd, sourceFiles) {
+  if (explicitlyChangesReturnRepresentation(taskText)) return [];
+  const conflicts = [];
+  for (const file of sourceFiles) {
+    const before = returnedElementRepresentation(gitBaselineText(cwd, file));
+    const after = returnedElementRepresentation(readTextIfSmall(cwd, file));
+    if (before && after && before !== after) {
+      conflicts.push(`public-return-representation-changed:${before}-to-${after}:${normalizePathCandidate(file)}`);
+    }
+  }
+  return conflicts;
+}
+
+export function returnRepresentationGuidance(taskText, cwd, sourceFiles) {
+  if (explicitlyChangesReturnRepresentation(taskText)) return [];
+  const guidance = [];
+  for (const file of sourceFiles.slice(0, 12)) {
+    const representation = returnedElementRepresentation(readTextIfSmall(cwd, file));
+    if (!representation) continue;
+    guidance.push(representation === "name"
+      ? `Existing public return elements in ${normalizePathCandidate(file)} are names/identifiers, not object values; preserve that representation unless the request explicitly changes it.`
+      : `Existing public return elements in ${normalizePathCandidate(file)} are object values, not names/identifiers; preserve that representation unless the request explicitly changes it.`);
+  }
+  return uniqueStrings(guidance).slice(0, 4);
+}

package/packages/piagent-core/extensions/shell-selector-policy.js

@@ -0,0 +1,55 @@
+export const SEARCH_COMMANDS = new Set(["grep", "egrep", "fgrep", "rg", "ripgrep"]);
+export const SEARCH_FILE_OPTIONS = new Set(["-f", "--file", "--exclude-from", "--ignore-file"]);
+export const SEARCH_GLOB_OPTIONS = new Set(["-g", "--glob", "--iglob", "--include", "--exclude", "--exclude-dir"]);
+export const SEARCH_PATTERN_OPTIONS = new Set(["-e", "--regexp", "--pattern"]);
+
+const SEARCH_EXCLUSION_OPTIONS = new Set(["--exclude", "--exclude-dir"]);
+const FIND_SELECTOR_OPTIONS = new Set(["-path", "-wholename", "-name", "-iname", "-lname", "-ilname", "-regex", "-iregex"]);
+const UNSAFE_FIND_ACTIONS = new Set([
+  "-delete", "-ok", "-okdir", "-fprint", "-fprint0", "-fprintf", "-fls"
+]);
+
+export function searchSelectorIsExclusion(commandName, optionName, value) {
+  if (!SEARCH_COMMANDS.has(commandName)) return false;
+  if (SEARCH_EXCLUSION_OPTIONS.has(optionName)) return true;
+  return ["rg", "ripgrep"].includes(commandName)
+    && ["-g", "--glob", "--iglob"].includes(optionName)
+    && String(value ?? "").startsWith("!");
+}
+
+export function findSelectorOption(optionName) {
+  return FIND_SELECTOR_OPTIONS.has(optionName);
+}
+
+export function excludedFindSelectorValue(tokens, index, commandName, downstreamFileConsumer = false) {
+  if (commandName !== "find" || tokens.some((token) => ["(", ")"].includes(token.value))) return false;
+  const selector = tokens[index - 1]?.value;
+  const selectorValue = tokens[index]?.value ?? "";
+  if (/[$`]/.test(selectorValue)) return false;
+  const unsafeTail = downstreamFileConsumer || tokens.some((token) => (
+    UNSAFE_FIND_ACTIONS.has(token.value)
+    || /^-exec(?:dir)?$/.test(token.value)
+  ));
+  if (tokens[index + 1]?.value === "-prune") return ["-path", "-wholename"].includes(selector)
+    && ["-o", "-or"].includes(tokens[index + 2]?.value)
+    && !unsafeTail
+    && !/[*?{\[]/.test(selectorValue.slice(selectorValue.lastIndexOf("/") + 1))
+    && !tokens.some((token) => ["!", "-not"].includes(token.value));
+  if (!findSelectorOption(selector)) return false;
+  if (unsafeTail || tokens.some((token) => ["-o", "-or", ","].includes(token.value))) return false;
+  let negations = 0;
+  for (let cursor = index - 2; cursor >= 0 && ["!", "-not"].includes(tokens[cursor].value); cursor -= 1) negations += 1;
+  return negations % 2 === 1;
+}
+
+export function searchSelectorWithinToken(commandName, word, attachedRgOption) {
+  if (!SEARCH_COMMANDS.has(commandName)) return undefined;
+  const equals = word.indexOf("=");
+  const option = equals > 0 ? word.slice(0, equals) : undefined;
+  if (option && (SEARCH_FILE_OPTIONS.has(option) || SEARCH_GLOB_OPTIONS.has(option))) {
+    return { option, value: word.slice(equals + 1) };
+  }
+  const grepFile = ["grep", "egrep", "fgrep"].includes(commandName) && /^-f.+/.test(word) ? word.slice(2) : undefined;
+  if (grepFile !== undefined) return { option: "-f", value: grepFile };
+  return ["-f", "-g"].includes(attachedRgOption?.option) ? attachedRgOption : undefined;
+}