@agentproto/apps 0.20.2 → 0.20.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentproto/apps",
-  "version": "0.20.2",
+  "version": "0.20.3",
   "description": "@agentproto/apps — a home for ready-made agentproto apps (teams of agents + their workflows), declared with @agentproto/app-kit. Import a team (code-team, content-team, …) and use any of its agents/workflows from your own host: in-process via toMastraAgents(), or emit its manifests to disk.",
   "keywords": [
     "agentproto",
@@ -175,7 +175,7 @@
     "zod": "^4.6.5",
     "@agentproto/agent": "0.2.5",
     "@agentproto/app-client": "0.4.1",
-    "@agentproto/app-kit": "1.6.1",
+    "@agentproto/app-kit": "1.6.2",
     "@agentproto/workflow": "0.7.1"
   },
   "peerDependencies": {

package/repo-maintenance/.agentproto/workflows/maintain/WORKFLOW.md

@@ -265,6 +265,12 @@ it when the item ends; `reviewCleanup` removes them all after the map, and
 entry.mjs's `finally` block removes them once more on failure or cancel — a
 `finally` step always runs.
 
+A review worktree sits outside every app zone, so a reviewer spawned there
+gets two extra READ-ONLY zones for its own session: the worktree and the
+repo's git dir (`git log/show/diff` read the object store). Both are checked
+against git's own worktree back-pointer first, and both are read-only, so a
+reviewer still cannot stash, checkout or commit in the shared repo.
+
 ## Out of scope, on purpose
 
 Recording a verdict via `branch_gc_verdict` never reclaims a branch by

package/repo-maintenance/.agentproto/workflows/maintain/entry.mjs

@@ -258,13 +258,30 @@ export function formatNameList(names, cap = REPORT_LIST_CAP) {
   return names.length > cap ? `${shown}, … and ${names.length - cap} more` : shown
 }
 
-/** Distinct error messages of a tolerant fan-out's rejected items, most
+/** `error` with the per-candidate parts — its review worktree path, branch
+ *  name and tip sha, then any other full sha — replaced by placeholders, so
+ *  one systemic failure hitting N candidates groups as ONE reason instead of
+ *  N "distinct" ones that differ only by `…/repo-<sha>`. */
+export function normalizeReviewError(error, candidate) {
+  let out = String(error ?? "")
+  const swap = (needle, placeholder) => {
+    if (typeof needle === "string" && needle.length > 0) out = out.split(needle).join(placeholder)
+  }
+  swap(candidate?.reviewWorktree, "<review worktree>")
+  swap(candidate?.sha, "<sha>")
+  swap(candidate?.name, "<branch>")
+  return out.replace(/\b[0-9a-f]{40}\b/g, "<sha>")
+}
+
+/** Distinct error messages of a tolerant fan-out's rejected items (normalized
+ *  by {@link normalizeReviewError} against `reviewCandidates[index]`), most
  *  frequent first: `[{ error, count }]`. */
-export function tallyReviewErrors(review) {
+export function tallyReviewErrors(review, reviewCandidates) {
   const counts = new Map()
   for (const r of Array.isArray(review?.results) ? review.results : []) {
     if (r?.status !== "rejected") continue
-    counts.set(r.error, (counts.get(r.error) ?? 0) + 1)
+    const error = normalizeReviewError(r.error, r.item ?? reviewCandidates?.[r.index])
+    counts.set(error, (counts.get(error) ?? 0) + 1)
   }
   return [...counts].map(([error, count]) => ({ error, count })).sort((a, b) => b.count - a.count)
 }
@@ -363,7 +380,7 @@ export function buildReport(b) {
   const reviewOutcome = Array.isArray(review)
     ? { succeeded: review.length, failed: 0, skipped: 0 }
     : { succeeded: 0, failed: 0, skipped: 0, ...(review ?? {}) }
-  const reviewErrors = tallyReviewErrors(review)
+  const reviewErrors = tallyReviewErrors(review, reviewCandidates)
   const gaps = b.steps.gaps ?? []
   const verdicts = collectCandidateVerdicts(reviewCandidates, b.steps.branchGcVerify)
   const applyMerged = b.input?.applyMerged === true

package/session-steward/.agentproto/workflows/session-steward/WORKFLOW.md

@@ -392,7 +392,7 @@ steps:
   - id: memoryWriteQueue
     kind: transform
     name: Verdict memory events to append
-    description: Entry-based — buildMemoryWriteQueue (a ledger write, never a session action).
+    description: Entry-based — buildMemoryWriteQueue (a ledger write, never a session action; empty unless apply).
 
   - id: memoryWrite
     kind: map
@@ -465,8 +465,9 @@ Every rule below is a pure function in `cron-rules.mjs`, pinned by
   why (`n live, m busy, k terminal, j excluded`).
 - **Host saturation (9).** If `host_load` is critical, the report lists
   orphans and big non-session processes FIRST — report only, no action.
-- **Verdict memory (10).** Each verdict is written to the app's `app_state`
-  ledger; a session judged the same verdict on an unchanged evidence
+- **Verdict memory (10).** On an `apply: true` pass each verdict is written to
+  the app's `app_state` ledger (a dry run reads the ledger but never writes it,
+  so its verdicts cannot be served as cached ones to a later real pass); a session judged the same verdict on an unchanged evidence
   fingerprint for `stableVerdictPasses` passes is served from cache and not
   re-judged. Operator disagreements are recorded as examples.
 
@@ -478,10 +479,10 @@ as observed, never nudged.
 ## Safety
 
 - `apply: false` (the default) mutates no SESSION: every session-mutating map
-  runs over an empty list. The one write a dry run performs is the append-only
-  verdict-memory ledger (`app_state_append`) — it never touches a session and
-  is what lets the cache accumulate across passes. Set `appId: ""` to disable
-  it entirely.
+  runs over an empty list, and a dry run writes nothing else either: the
+  append-only verdict-memory ledger (`app_state_append`) is read but only
+  appended to on an `apply: true` pass, so a dry run can never influence a later
+  real close. Set `appId: ""` to disable the memory entirely.
 - `session_wrapup_apply` re-classifies each id right before acting and always
   refuses `keep`-class ids; this workflow never feeds it one.
 - Rules only ever close `close`/`stuck` ids; a `keepAlive` session is never

package/session-steward/.agentproto/workflows/session-steward/cron-rules.mjs

@@ -64,7 +64,7 @@ export function isUsefulLoopCommand(signature) {
 }
 
 const READ_TOOLS = new Set(["read", "cat", "rg", "grep", "sed", "head", "tail", "less", "view", "readfile"])
-const READ_COMMAND = /\b(cat|rg|grep|sed|head|tail|less|view)\b/
+const READ_VERB_WORD = /^["']?(cat|rg|grep|sed|head|tail|less|view)["']?$/
 
 /**
  * The file a read-like call targeted, or `null`. Best-effort: an in-agent
@@ -76,15 +76,26 @@ export function readTargetOf(record) {
   const tool = String(record?.tool ?? "").toLowerCase()
   const command = str(record?.command)
   const args = Array.isArray(record?.args) ? record.args.map(String) : []
-  const isRead = READ_TOOLS.has(tool) || (command !== undefined && READ_COMMAND.test(command))
-  if (!isRead) return null
-  const tokens = command !== undefined ? command.split(/\s+/) : args
-  for (const raw of tokens) {
-    const t = raw.replace(/^['"]|['"]$/g, "")
-    if (!t || t.startsWith("-") || t.includes("=")) continue
-    if (t.includes("/") || /\.(md|ts|tsx|js|mjs|cjs|json|txt|py|go|rs|sql|yml|yaml|toml)$/.test(t)) return t
+  const readTool = READ_TOOLS.has(tool)
+  if (!readTool && command === undefined) return null
+  // A shell line is several commands: only a segment that STARTS with a read
+  // verb reads a file. `cd <dir> &&`, `git log | head` and `--grep=…` do not.
+  const segments = command !== undefined && !readTool ? command.split(/&&|\|\||\||;/) : [undefined]
+  for (const seg of segments) {
+    let tokens = seg !== undefined ? seg.trim().split(/\s+/) : command !== undefined ? command.split(/\s+/) : args
+    if (seg !== undefined) {
+      const first = tokens.findIndex((t) => !t.includes("=") || t.startsWith("-"))
+      if (first < 0 || !READ_VERB_WORD.test(tokens[first])) continue
+      tokens = tokens.slice(first + 1)
+    }
+    for (const raw of tokens) {
+      const t = raw.replace(/^['"]|['"]$/g, "")
+      if (!t || t.startsWith("-") || t.includes("=")) continue
+      if (t.includes("/") || /\.(md|ts|tsx|js|mjs|cjs|json|txt|py|go|rs|sql|yml|yaml|toml)$/.test(t)) return t
+    }
+    if (seg === undefined) return args[0] ?? null
   }
-  return args[0] ?? null
+  return null
 }
 
 function topEntry(counts) {
@@ -115,7 +126,11 @@ export function detectLoop(records, opts = {}) {
     const ts = Date.parse(r?.ts)
     return Number.isFinite(ts) && ts <= nowMs + 1000 && nowMs - ts <= windowMs
   })
-  const calls = inWindow.filter((r) => !isUsefulLoopCommand(callSignature(r)))
+  // A record with no command and no args (an in-agent `read`/`edit` call) has
+  // nothing but its tool name to compare, so three of them in ten minutes is
+  // normal work, not a loop — leave it out of every repetition signal.
+  const informative = inWindow.filter((r) => str(r?.command) !== undefined || (Array.isArray(r?.args) && r.args.length > 0))
+  const calls = informative.filter((r) => !isUsefulLoopCommand(callSignature(r)))
   const counts = new Map()
   const reads = new Map()
   for (const r of calls) {
@@ -146,7 +161,8 @@ export function detectLoop(records, opts = {}) {
       ratio: Math.round(ratio * 100) / 100,
       maxVerbatim,
       maxReads,
-      usefulExcluded: inWindow.length - total,
+      usefulExcluded: informative.length - total,
+      anonymousExcluded: inWindow.length - informative.length,
       topCommand: top ? top.key : null,
       topCommandCount: top ? top.count : 0,
     },
@@ -278,6 +294,9 @@ export function prNumbersOf(session) {
   return [...nums].sort((a, b) => a - b)
 }
 
+/** Relabel verdict for "no positive evidence either way". */
+export const UNKNOWN_VERDICT = "unknown"
+
 const fmtPrs = nums => nums.map(n => `#${n}`).join(", ")
 const isMergedState = state => state === "merged" || state === "MERGED"
 
@@ -285,7 +304,9 @@ const isMergedState = state => state === "merged" || state === "MERGED"
  * A terminal session that still carries no derived outcome and no wrapup
  * flag is a relabel CANDIDATE — visible instead of invisible, as the log
  * asks. The proposed verdict is `done` when the session's own record shows a
- * PR (merged, or merely opened — the PR is the hand-off), else `abandoned`.
+ * PR (merged, or merely opened — the PR is the hand-off), else `unknown`: a
+ * session with no PR is as likely finished as abandoned, and only evidence
+ * ({@link refineRelabel}) can say which.
  * `reason` carries the evidence (`PR #1738 merged`, `PRs #1738, #1740 opened`).
  */
 export function terminalRelabelCandidate(session) {
@@ -294,14 +315,21 @@ export function terminalRelabelCandidate(session) {
   if (session?.wrapupFlag) return { candidate: false, reason: "already flagged" }
   const prs = prNumbersOf(session)
   const wt = session?.worktree?.pr
-  if (isMergedState(wt?.state)) {
-    const n = Number.isInteger(wt.number) ? [wt.number] : prs
-    return { candidate: true, proposedVerdict: "done", reason: n.length > 0 ? `PR ${fmtPrs(n)} merged` : "PR merged", prs }
+  // A worktree can be shared by several sessions, so its merged PR is not
+  // proof THIS one finished: a session whose last turn errored is not credited
+  // with it, and a PR the session did not record itself is labelled as the
+  // worktree's.
+  const ownMerged = Number.isInteger(wt?.number) && prs.includes(wt.number)
+  if (isMergedState(wt?.state) && (ownMerged || !session?.lastTurnErroredAt)) {
+    if (Number.isInteger(wt.number)) {
+      return { candidate: true, proposedVerdict: "done", reason: `PR ${fmtPrs([wt.number])} merged${prs.includes(wt.number) ? "" : " (worktree)"}`, prs }
+    }
+    return { candidate: true, proposedVerdict: "done", reason: prs.length > 0 ? `PR ${fmtPrs(prs)} merged` : "PR merged", prs }
   }
   if (prs.length > 0) {
     return { candidate: true, proposedVerdict: "done", reason: `PR${prs.length > 1 ? "s" : ""} ${fmtPrs(prs)} opened`, prs }
   }
-  return { candidate: true, proposedVerdict: "abandoned", reason: "terminal, no outcome recorded", prs }
+  return { candidate: true, proposedVerdict: UNKNOWN_VERDICT, reason: "terminal, no PR recorded — outcome unknown", prs }
 }
 
 /**
@@ -315,19 +343,34 @@ export function refineRelabel(item, evidence) {
   const wt = evidence.worktree?.pr
   const state = wt?.state ?? evidence.pullRequests?.state ?? null
   const known = Array.isArray(item?.prs) ? item.prs : []
-  const merged = isMergedState(state) || (evidence.pullRequests?.merged ?? 0) > 0
+  // `pullRequests.merged` and `worktree.pr` describe the whole worktree, which
+  // sibling sessions share: a session that recorded no PR of its own and whose
+  // last turn errored is not credited with a sibling's merge.
+  const ownPr = known.length > 0 || (evidence.pullRequests?.opened ?? 0) > 0
+  const errored = typeof evidence.lastTurnError === "string" && evidence.lastTurnError.trim() !== ""
+  const credited = ownPr || !errored
+  const merged = credited && (isMergedState(state) || (evidence.pullRequests?.merged ?? 0) > 0)
   if (merged) {
     const n = Number.isInteger(wt?.number) ? wt.number : known.length === 1 ? known[0] : undefined
     const others = known.filter(k => k !== n)
-    const reason = (n !== undefined ? `PR #${n} merged` : "PR merged") + (others.length > 0 && n !== undefined ? `; also opened ${fmtPrs(others)}` : "")
+    // A PR number the session did not record itself is the worktree's.
+    const shared = n !== undefined && !known.includes(n) ? " (worktree)" : ""
+    const reason = (n !== undefined ? `PR #${n} merged${shared}` : "PR merged") + (others.length > 0 && n !== undefined ? `; also opened ${fmtPrs(others)}` : "")
     return { ...item, proposedVerdict: "done", reason }
   }
   if (item?.proposedVerdict === "done") return item
-  if (state === "open" || state === "OPEN") {
+  if (credited && (state === "open" || state === "OPEN")) {
     return { ...item, proposedVerdict: "done", reason: Number.isInteger(wt?.number) ? `PR #${wt.number} open` : "PR open" }
   }
   const opened = evidence.pullRequests?.opened ?? 0
   if (opened > 0) return { ...item, proposedVerdict: "done", reason: `${opened} PR${opened > 1 ? "s" : ""} opened` }
+  // No PR: `abandoned` needs positive evidence the session did not finish.
+  if (item?.proposedVerdict === UNKNOWN_VERDICT) {
+    if (typeof evidence.lastTurnError === "string" && evidence.lastTurnError.trim()) {
+      return { ...item, proposedVerdict: "abandoned", reason: `no PR, last turn errored: ${evidence.lastTurnError.trim().slice(0, 80)}` }
+    }
+    if (evidence.turnsCompleted === 0) return { ...item, proposedVerdict: "abandoned", reason: "no PR, no turn ever completed" }
+  }
   return item
 }
 

package/session-steward/.agentproto/workflows/session-steward/entry.mjs

@@ -12,9 +12,10 @@
 // RE-CLASSIFIES each id itself immediately before acting and refuses
 // `keep`-class ids outright. On top of that, this workflow:
 //   - mutates no SESSION unless `apply` is true (every session-mutating map
-//     runs over an empty list otherwise). The one dry-run write is the
-//     append-only verdict-memory ledger (`app_state_append`) — never a
-//     session, and disableable with `appId: ""`;
+//     runs over an empty list otherwise). A dry run writes nothing at all:
+//     the append-only verdict-memory ledger (`app_state_append`) is read but
+//     only appended to when `apply` is true, so a dry run's verdicts can
+//     never be served as cached verdicts to a later real pass;
 //   - only ever feeds `close`/`stuck` ids to the rules pass — a `keepAlive`
 //     session can only ever be `judge` class, so rules never close it;
 //   - drops the caller's own session from every candidate list;
@@ -664,6 +665,9 @@ export function buildReport(b) {
   } else if (memory instanceof Map && memory.size > 0) {
     lines.push(`- verdict memory: ${memory.size} session(s) known` + (cachedCount > 0 ? `, ${cachedCount} served from cache` : ""))
   }
+  if (!s.apply && b.steps.memoryApp?.appId) {
+    lines.push("- verdict memory was read but not written (dry run)")
+  }
 
   return lines.join("\n")
 }
@@ -804,6 +808,24 @@ export function mergeNeverRan(candidates, scan) {
   }
 }
 
+/** A rule-certain `close` whose session's last turn errored did not finish —
+ *  parentEnded / merged-worktree only says the parent moved on. Closing it
+ *  would record `done` on a failed run, so demote it to the judge list. */
+export function demoteErroredCloses(candidates, scan) {
+  const errored = new Set((scan?.idle ?? []).filter(r => r?.lastTurnErroredAt).map(r => r.sessionId))
+  const close = candidates?.close ?? []
+  const demoted = close.filter(e => errored.has(e.sessionId))
+  if (demoted.length === 0) return candidates
+  return {
+    ...candidates,
+    close: close.filter(e => !errored.has(e.sessionId)),
+    judge: [
+      ...(candidates?.judge ?? []),
+      ...demoted.map(e => ({ ...e, class: "judge", reasons: [...(e.reasons ?? []), "last turn errored — not auto-closed"] })),
+    ],
+  }
+}
+
 /** `tool_calls_list` map item → the loop verdict + stats for one session. */
 export function analyzeLoopItem(b) {
   const item = b.item ?? {}
@@ -923,10 +945,12 @@ export function applyRelabelEvidence(relabelQueue, evidenceResult) {
   return (relabelQueue ?? []).map(r => (bySession.has(r.sessionId) ? refineRelabel(r, bySession.get(r.sessionId)) : r))
 }
 
-/** The `app_state` events to append for this pass's verdicts. The memory is
- *  written on every pass (it is a ledger, never a session action) so streaks
- *  accumulate and the cache can engage. */
+/** The `app_state` events to append for this pass's verdicts. Written only on
+ *  an `apply` pass (so streaks accumulate and the cache can engage); a dry run
+ *  reads memory but never writes it, or its verdicts would be reused by the
+ *  next real pass instead of being re-judged. */
 export function buildMemoryWriteQueue(finalVerdicts, settings) {
+  if (!settings?.apply) return []
   if (!settings?.appId) return []
   const out = []
   for (const r of finalVerdicts ?? []) {
@@ -1000,7 +1024,7 @@ export default {
     { id: "liveSessions", kind: "tool", tool: "session_list", inputs: { full: true } },
     { id: "scan", kind: "transform", compute: b => scanLive(b.steps.liveSessions, b.steps.settings, Date.now()) },
     // Never-ran 0/0 sessions are `stuck` immediately, never judged (item 3).
-    { id: "candidatesPlus", kind: "transform", compute: b => mergeNeverRan(b.steps.candidates, b.steps.scan) },
+    { id: "candidatesPlus", kind: "transform", compute: b => demoteErroredCloses(mergeNeverRan(b.steps.candidates, b.steps.scan), b.steps.scan) },
     { id: "ruleApplyQueue", kind: "transform", compute: b => buildRuleApplyQueue(b.steps.candidatesPlus, b.steps.settings) },
     {
       // Empty unless `apply` — a dry run dispatches no apply call at all.
@@ -1210,7 +1234,8 @@ export default {
       ],
     },
     // Verdict memory write-back (item 10) — a ledger append, never a session
-    // action; best-effort (an uninstalled app just yields no memory).
+    // action; empty unless `apply`; best-effort (an uninstalled app just
+    // yields no memory).
     { id: "memoryWriteQueue", kind: "transform", compute: b => buildMemoryWriteQueue(b.steps.finalVerdicts, { ...b.steps.settings, appId: b.steps.memoryApp?.appId ?? "" }) },
     {
       id: "memoryWrite",