@brainervirus/workit-core 8.19.0 → 8.19.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "8.19.0",
+  "version": "8.19.2",
   "private": false,
   "description": "Workit shared core — task, policy, evidence, review, decision, worker, and writer state for agentic coding workflows",
   "keywords": [

package/skills/workit-implement/SKILL.md

@@ -24,7 +24,10 @@ description: Build a requested change in small verified steps - follow local pat
    lease waits and names its holder (`workit lock status`).
 5. Prove the feature on its real surface with the project's `verify-<app>`
    skill; none yet? Write one (workit-verify-app). Tests show branch behavior,
-   not that the feature works.
+   not that the feature works. The report carries what you observed: a UI
+   change a screenshot or console/network check (chrome devtools or
+   agent-browser), an API a quoted real response. App not runnable? Say so
+   plainly, never claim success.
 6. Commit: `workit git commit -m "<type>: <what>" -- <paths>` (or `--all`).
    No endpoint named? Stop here and state the next command. Hand delivery to
    ship, which pushes and opens the PR with its body shape (workit-ship), only
@@ -55,8 +58,7 @@ flag was never invoked)
 
 Good: "Added `--since`. measured: `workit check test` exit 0;
 `mytool log --since 2d` printed 3 entries against the fixture repo. inferred:
-the GitLab path behaves the same (shared parser, not run). Verification handed
-to the verifier agent."
+the GitLab path behaves the same (not run). Handed to the verifier agent."
 
 ## Check
 

package/skills/workit-verify-app/SKILL.md

@@ -27,7 +27,10 @@ way a user would.
    - **Drive:** how to exercise it: CLI invocations, `curl` against routes, a
      browser tool for UI, with fixture data.
    - **Evidence:** what to capture (exit code, response body, screenshot path)
-     and the command that records it.
+     and the command that records it. A UI is driven with chrome devtools or
+     agent-browser, with a screenshot or console/network observation; an API
+     with a real call, response quoted. The report carries the observation.
+     App not runnable? Say so plainly, never claim success.
    - **Cleanup:** stop processes, remove temp data.
    - **Feature map:** feature, how to drive it, expected observation.
 3. **Prove it end-to-end once:** launch, drive one feature, capture evidence,
@@ -54,7 +57,8 @@ report `clean`, `changed` (what) or `blocked` (why).
 Bad: "Verify by running the tests." (that is not the real surface)
 
 Good: "Launch `bun run dev` (ready: `listening on :5173`, 30 s). Drive:
-`curl -s localhost:5173/api/health` returns `{"ok":true}`. Evidence:
+`curl -s localhost:5173/api/health` returned `{"ok":true}`; screenshot of
+/settings at .workit-scratch/settings.png. Evidence:
 `workit check --name verify-web -- bun scripts/smoke.ts` exit 0."
 
 ## Check

package/skills/workit-verify-app/references/template.md

@@ -30,6 +30,8 @@ description: Launch, drive and observe <app> on its real surface (<cli|web|api>)
 ## Evidence
 `workit check --name verify-<app> -- <driver command>` records exit code and log.
 Screenshots go to `<tmp dir>/verify-<app>/<feature>.png`; cite the path.
+UI: also report a console or network observation. API: quote the real response.
+If the app cannot be run, say so plainly instead of claiming success.
 
 ## Cleanup
 `<command>` (stop servers, remove `<tmp dir>`).

package/src/core/heavy-words.ts

@@ -32,7 +32,7 @@ const wordsOf = (command: string): string[] =>
     )
     .filter(Boolean);
 
-const stateDir = (env: NodeJS.ProcessEnv): string => {
+export const stateDir = (env: NodeJS.ProcessEnv): string => {
   if (env.WORKFLOW_TOOLKIT_STATE) return env.WORKFLOW_TOOLKIT_STATE;
   if (env.XDG_STATE_HOME) return path.join(env.XDG_STATE_HOME, "workit");
   const home = env.HOME || os.homedir();

package/src/hooks/write-gate.ts

@@ -17,6 +17,7 @@ import {
   type LiveDeps,
   type LiveOwner,
 } from "../core/live-session";
+import { resolveStateDir } from "../core/logger";
 import { workspaceLiveSessionGuard } from "../core/workspaces";
 import { appendHookObserved, ledgerPath } from "../ledger";
 import type { HookDecision } from "./protocol";
@@ -41,7 +42,8 @@ const canonical = (file: string): string => {
   let rest = "";
   for (let dir = path.resolve(file); ; dir = path.dirname(dir)) {
     try {
-      return path.join(realpathSync(dir), rest);
+      // Native resolution also expands Windows 8.3 short names (RUNNER~1).
+      return path.join(realpathSync.native(dir), rest);
     } catch {
       if (path.dirname(dir) === dir) return path.resolve(file);
       rest = rest ? path.join(path.basename(dir), rest) : path.basename(dir);
@@ -325,9 +327,10 @@ const POPD = new Set(["popd", "pop-location"]);
 
 /** A `cd` operand resolved against `dir`; undefined when it cannot be known. */
 const cdInto = (dir: string | undefined, words: string[]): string | undefined => {
-  const target = words.slice(1).find((word) => !word.startsWith("-") || word === "-");
-  // Only a leading `~` expands; a mid-path `~` is literal (Windows 8.3
+  const named = words.slice(1).find((word) => !word.startsWith("-") || word === "-");
+  // Only a leading `~` or `$HOME` expands; a mid-path `~` is literal (Windows 8.3
   // short names like RUNNER~1).
+  const target = named === undefined ? undefined : homeExpanded(named);
   if (dir === undefined || target === "-" || (target && /^~|[$`*?]/.test(target))) return undefined;
   return target === undefined ? os.homedir() : path.resolve(dir, target);
 };
@@ -335,6 +338,12 @@ const cdInto = (dir: string | undefined, words: string[]): string | undefined =>
 const quoteWord = (word: string): string =>
   /^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replaceAll("'", "'\\''")}'`;
 
+/** A leading `~`, `$HOME` or `${HOME}` the shell would expand. */
+const homeExpanded = (file: string): string => {
+  const match = /^(?:~|\$HOME|\$\{HOME\})(?=\/|$)/.exec(file);
+  return match ? (process.env.HOME || os.homedir()) + file.slice(match[0].length) : file;
+};
+
 /**
  * Per top-level segment, the files it writes (redirects, `touch`, `rm`,
  * `sed -i`…) and `workit git commit|branch`, resolved against the
@@ -351,8 +360,10 @@ const segmentTargets = (
   let dir: string | undefined = cwd;
   let stack: Array<string | undefined> = [];
   const groups: Array<{ dir: string | undefined; stack: Array<string | undefined> }> = [];
-  const at = (file: string) =>
-    path.isAbsolute(file) ? file : dir === undefined ? null : path.resolve(dir, file);
+  const at = (file: string) => {
+    const home = homeExpanded(file);
+    return path.isAbsolute(home) ? home : dir === undefined ? null : path.resolve(dir, home);
+  };
   for (const segment of segmentsOf(command, dialect)) {
     if (segment.group === "open") {
       groups.push({ dir, stack: [...stack] });
@@ -474,6 +485,65 @@ const claimAll = (owner: LiveOwner, targets: readonly string[], deps?: LiveDeps)
 const liveTargets = (cwd: string, paths: readonly string[] | null): string[] =>
   paths?.length ? paths.map((file) => path.resolve(cwd, file)) : [path.join(cwd, DIR_TARGET)];
 
+// --- the issued-registry guard (#292) ---------------------------------------
+
+/**
+ * The files an agent tool call writes under `<state>/issued*`: the issued-id
+ * records and their token hashes. Only the hook and the CLI write there; an
+ * agent that could would forge an issued session or token by hand.
+ */
+const issuedTarget = (cwd: string, targets: readonly string[]): string | null => {
+  const state = resolveStateDir();
+  const found = targets.find((target) =>
+    underIssued(state, cwd, homeExpanded(target), process.platform, canonical),
+  );
+  return found ?? null;
+};
+
+/**
+ * Whether `target` (resolved against `cwd`) is `<state>/issued*` or inside
+ * it. Pure over `platform`, so Windows shapes are testable anywhere: mixed
+ * `\` and `/`, drive-letter case, and the `/c/Users/...` form a POSIX shell
+ * on Windows uses. `real` resolves symlinks and 8.3 short names (RUNNER~1) on
+ * the live platform.
+ */
+export const underIssued = (
+  state: string,
+  cwd: string,
+  target: string,
+  platform: NodeJS.Platform = process.platform,
+  real: (file: string) => string = (file) => file,
+): boolean => {
+  const win = platform === "win32";
+  const p = win ? path.win32 : path.posix;
+  const fold = (value: string) => (win || platform === "darwin" ? value.toLowerCase() : value);
+  const named = win ? target.replace(/^\/([a-zA-Z])(?=\/|$)/, "$1:") : target;
+  const relative = p.relative(fold(real(p.resolve(state))), fold(real(p.resolve(cwd, named))));
+  if (relative.startsWith("..") || p.isAbsolute(relative)) return false;
+  return relative.split(p.sep)[0].startsWith("issued");
+};
+
+/**
+ * A POSIX shell drops an unquoted `\` before the analysis sees the words, so
+ * `> C:\state\issued\x` loses its separators. On Windows, a command that
+ * writes and spells out the registry path is denied.
+ */
+const unquotedWindowsIssued = (command: string): boolean => {
+  if (process.platform !== "win32" || !command.includes("\\")) return false;
+  const flat = (value: string) => value.replaceAll("\\", "/").toLowerCase();
+  return flat(command).includes(`${flat(resolveStateDir())}/issued`) && shellWrites(command).writes;
+};
+
+const issuedDeny = (file: string): HookDecision => {
+  const unblock =
+    "Issued ids and tokens are written only by Workit's SubagentStart hook. Run the verifier or reviewer agent so the host issues its own session; never edit the issued registries by hand.";
+  return {
+    kind: "deny",
+    reason: `workit issued-registry guard: ${file} is under Workit's issued-session state. ${unblock}`,
+    unblock,
+  };
+};
+
 /**
  * Deny a working-tree edit while the branch task has unmet before-write
  * requirements. `paths` are the files the tool writes, or null when unknown
@@ -488,6 +558,8 @@ export function writeGate(
   owner?: LiveOwner | null,
   deps?: LiveDeps,
 ): HookDecision {
+  const forged = paths?.length ? issuedTarget(cwd, paths) : null;
+  if (forged) return issuedDeny(forged);
   if (!owner) return beforeWriteGate(cwd, paths);
   const targets = liveTargets(cwd, paths);
   const live = liveGate(owner, targets, deps);
@@ -511,6 +583,14 @@ export function shellGate(
   dialect: ShellDialect = "posix",
   deps?: LiveDeps,
 ): HookDecision {
+  try {
+    const forged =
+      issuedTarget(cwd, segmentTargets(cwd, command, dialect)) ??
+      (unquotedWindowsIssued(command) ? "the issued registry" : null);
+    if (forged) return issuedDeny(forged);
+  } catch {
+    // Fail open, like the other shell analyses here.
+  }
   const writes = shellWrites(command);
   let targets: string[] = [];
   if (owner) {