@agentproto/apps 0.20.2 → 0.21.0

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

@@ -91,11 +91,11 @@ inputs:
     type: array
     description: >-
       Origins that may be closed under the current rules. A trailing `*` is a
-      prefix wildcard. Default `["cron:*", "gate"]`. Executors (a session with
+      prefix wildcard. Default `["cron:*", "gate", "workflow", "review"]`. Executors (a session with
       a `parentSessionId`) are closable regardless.
     items:
       type: string
-    default: ["cron:*", "gate"]
+    default: ["cron:*", "gate", "workflow", "review"]
 outputs: {}
 steps:
   - id: modelRoles
@@ -172,6 +172,7 @@ steps:
           sessionIds: [$item.sessionId]
           verdict: $item.verdict
           note: $item.note
+          wait: true
 
   - id: installedApps
     kind: tool
@@ -388,11 +389,12 @@ steps:
           verdict: $item.verdict
           judgedBy: $item.judgedBy
           note: $item.note
+          wait: true
 
   - 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 +467,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 +481,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
@@ -494,7 +497,8 @@ as observed, never nudged.
   `origin`/`parentSessionId` runs through the pure `decideAction`
   (`origin-policy.mjs`): a `userOrigins` match (`chat-starter`, `vscode` by
   default) or a root with no origin and no parent is FLAG-ONLY, even with
-  `apply: true` and a confident `done` verdict. `cron:*`, `gate`, and
+  `apply: true` and a confident `done` verdict. `cron:*`, `gate`, `workflow`
+  (workflow-step sessions), `review` (reviewer lanes) and
   executors (a session with a `parentSessionId`) stay closeable. Both lists
   are workflow inputs; a trailing `*` is a prefix wildcard.
 - The report carries an `origin` column and the retained action (e.g.

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 ?? []) {
@@ -976,7 +1000,7 @@ export default {
     appId: { type: "string", description: `Installed app whose \`app_state\` ledger holds the verdict memory. Default ${DEFAULT_APP_ID}.` },
     stableVerdictPasses: { type: "number", description: `Consecutive passes on an unchanged evidence fingerprint before the judge cache stops re-judging. Default ${DEFAULT_STABLE_VERDICT_PASSES}.`, default: DEFAULT_STABLE_VERDICT_PASSES },
     userOrigins: { type: "array", description: `Origins that are ALWAYS flag-only, never closed (a human is in the loop). Trailing \`*\` is a prefix wildcard. Default ${JSON.stringify(DEFAULT_USER_ORIGINS)}.`, items: { type: "string" }, default: DEFAULT_USER_ORIGINS },
-    closableOrigins: { type: "array", description: `Origins that may be closed under the current rules (cron jobs, gates). Trailing \`*\` is a prefix wildcard. Executors (a session with a parentSessionId) are closable regardless. Default ${JSON.stringify(DEFAULT_CLOSABLE_ORIGINS)}.`, items: { type: "string" }, default: DEFAULT_CLOSABLE_ORIGINS },
+    closableOrigins: { type: "array", description: `Origins that may be closed under the current rules (cron jobs, gates, workflow steps, reviewer lanes). Trailing \`*\` is a prefix wildcard. Executors (a session with a parentSessionId) are closable regardless. Default ${JSON.stringify(DEFAULT_CLOSABLE_ORIGINS)}.`, items: { type: "string" }, default: DEFAULT_CLOSABLE_ORIGINS },
   },
   outputs: {},
   steps: [
@@ -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.
@@ -1014,7 +1038,10 @@ export default {
           id: "autoApplyOne",
           kind: "tool",
           tool: "session_wrapup_apply",
-          inputs: { sessionIds: ["$item.sessionId"], verdict: "$item.verdict", note: "$item.note" },
+          // `wait: true` — past its 25 s default `waitMs` the tool returns a
+          // bare `{ jobId, status: "running" }` and the report would show no
+          // outcome for a session that did get closed.
+          inputs: { sessionIds: ["$item.sessionId"], verdict: "$item.verdict", note: "$item.note", wait: true },
         },
       ],
     },
@@ -1205,12 +1232,14 @@ export default {
           id: "judgedApplyOne",
           kind: "tool",
           tool: "session_wrapup_apply",
-          inputs: { sessionIds: ["$item.sessionId"], verdict: "$item.verdict", judgedBy: "$item.judgedBy", note: "$item.note" },
+          // `wait: true`: same as autoApplyOne.
+          inputs: { sessionIds: ["$item.sessionId"], verdict: "$item.verdict", judgedBy: "$item.judgedBy", note: "$item.note", wait: true },
         },
       ],
     },
     // 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",

package/session-steward/.agentproto/workflows/session-steward/origin-policy.mjs

@@ -12,7 +12,7 @@ export const DEFAULT_USER_ORIGINS = ["chat-starter", "vscode"]
 /** Origins the steward MAY close under the current rules. `cron:*` matches
  *  every cron-spawned job (`origin: "cron:<jobId>"`); `gate` matches
  *  supervision-gate sessions. */
-export const DEFAULT_CLOSABLE_ORIGINS = ["cron:*", "gate"]
+export const DEFAULT_CLOSABLE_ORIGINS = ["cron:*", "gate", "workflow", "review"]
 
 /** The reason shown (and recorded) when a would-be close is bounded by origin. */
 export const USER_ORIGIN_REASON = "flag (origine utilisateur)"
@@ -46,7 +46,7 @@ export function resolveOriginPolicy(policy) {
 /** The origin class of a candidate:
  *  - `"user"` — human-launched: a `userOrigins` match, OR a root with no
  *    origin and no parent. FLAG ONLY, never close.
- *  - `"closable"` — a `closableOrigins` match (cron:*, gate) or an executor
+ *  - `"closable"` — a `closableOrigins` match (cron:*, gate, workflow, review) or an executor
  *    (has a `parentSessionId`). Close allowed under the current rules.
  *  `userOrigins` wins over both `closableOrigins` and the executor rule, so a
  *  `vscode` executor is still user-origin. An unrecognized root origin is

package/session-steward/README.md

@@ -53,7 +53,7 @@ the `userOrigins` / `closableOrigins` inputs:
   `origin` and no `parentSessionId` (a human launched it). A would-be close —
   even a rule-certain `close`/`stuck`, even a confident `done` — is recorded
   as a `needs-input` flag with reason `flag (origine utilisateur)`.
-- **Close allowed:** `cron:*`, `gate`, and executors (a session with a
+- **Close allowed:** `cron:*`, `gate`, `workflow` (step sessions), `review` (reviewer lanes), and executors (a session with a
   `parentSessionId`).
 
 A trailing `*` in either list is a prefix wildcard. The report carries the

package/session-steward/routines/session-steward-hourly/ROUTINE.md

@@ -23,10 +23,10 @@ target:
     askSessions: false
     # Origin policy (the committed default): never close a human's session.
     # `chat-starter`/`vscode` (and any root with no origin and no parent) are
-    # FLAG-ONLY; `cron:*` jobs, `gate` sessions, and executors (a session with
+    # FLAG-ONLY; `cron:*` jobs, `gate`, `workflow` and `review` sessions, and executors (a session with
     # a parentSessionId) stay closeable. A trailing `*` is a prefix wildcard.
     userOrigins: ["chat-starter", "vscode"]
-    closableOrigins: ["cron:*", "gate"]
+    closableOrigins: ["cron:*", "gate", "workflow", "review"]
 retry:
   max_attempts: 1
   backoff: fixed
@@ -68,7 +68,7 @@ The steward bounds every action by the candidate's `origin` (pure
   `origin` and no `parentSessionId` (a human launched it). A would-be close —
   even a rule-certain `close`/`stuck`, even a confident `done` — becomes a
   `needs-input` flag with reason `flag (origine utilisateur)`.
-- **Close allowed:** `cron:*` (any cron job), `gate`, and executors (a
+- **Close allowed:** `cron:*` (any cron job), `gate`, `workflow` (workflow-step sessions), `review` (reviewer lanes), and executors (a
   session with a `parentSessionId`).
 
 Both lists are workflow inputs (`userOrigins`, `closableOrigins`); the values