@monster-orange/den 0.4.0 → 0.4.2

package/docs/reference.md

@@ -0,0 +1,177 @@
+# Den reference
+
+The technical reference that used to be the README. It will be split into separate pages (configuration, CLI, manifests, edge, secrets, tests, MCP) as part of DOC-2.
+
+## Make it your own
+
+1. **Create** a distribution named after your product:
+
+   ```sh
+   npx @monster-orange/den create acme      # → ./acme
+   cd acme && npm install
+   ```
+
+2. **Name** it: `den.yml` holds `product: { name: acme }`, so the CLI is
+   `./bin/acme`, env vars are `ACME_*`, state lives in `~/.acme`. Pass
+   `--cli`, `--env-prefix` or `--title` to `create`, or edit `den.yml`.
+3. **Brand** it: `brand:` in `config/acme.yml` sets the name, tagline and
+   banner people see in the CLI and web UI.
+4. **Point it at your repos**: set `github_org` in `config/acme.yml`, then
+   `./bin/acme register ../shop-api` (or add a manifest per repo under
+   `manifests/`).
+5. **Run** it: `./bin/acme up`, `./bin/acme web`, `make test`.
+
+Every field, the bin shim, the make fragment and upgrading are in
+[docs/distributions.md](distributions.md);
+[examples/distribution/](../examples/distribution) is what `create acme` writes.
+
+## Distributions
+
+You run Den through a small repo of your own (a _distribution_):
+
+```
+my-dev/
+├── den.yml               # who this distribution is (below)
+├── package.json          # pins an exact @monster-orange/den version
+├── config/<name>.yml     # your org config
+├── config/environments/  # one <env>.json per environment
+├── manifests/            # manifests for repos that don't carry their own
+├── tests/pillars/<pillar>/   # your own suites (e.g. tests/pillars/perf/<module>/test.js)
+├── bin/<cli>             # shim: DEN_ROOT=<this dir> exec node_modules/@monster-orange/den/bin/den
+└── Makefile              # include node_modules/@monster-orange/den/make/den.mk
+```
+
+`den.yml` names the product. Every runtime name derives from it:
+
+```yaml
+product:
+  name:
+    acme # CLI "acme", env vars ACME_*, config/acme.yml,
+    # manifests .acme.yml, state ~/.acme,
+    # managed clones .acme-services/, workspaces acme-workspaces/
+  # Override any of them: cli, env_prefix, config, manifest, state_dir,
+  # services_dir, workspaces_dir
+```
+
+Den's own checkout is a distribution named `den`, so in this repo the CLI is
+`./bin/den`, the config is `config/den.yml`, and env vars are `DEN_*`.
+
+## Repos opt in with a manifest
+
+A repo joins by carrying a manifest at its root (`.<name>.yml`, e.g.
+`.den.yml`) whose commands delegate to the repo's own targets. Den never
+reaches inside a repo beyond that. When a repo has no manifest, the
+distribution can hold one for it in `manifests/<repo>.<name>.yml`; the repo's
+own manifest always wins.
+
+```yaml
+# demo-api: a self-contained service. Nothing it calls, so it starts alone.
+version: 1
+name: demo-api
+application: shop # the application this repo belongs to (den apps)
+compose:
+  files: [docker-compose.yml]
+  routes:
+    api: api:8080 # https://api.demo-api.<edge domain>
+services:
+  demo-api:
+    commands:
+      local:
+        setup: make setup
+        preflight: make test
+# OWASP ZAP target for the security pillar (`make test-sec-api env=local`).
+security:
+  api:
+    hosts:
+      local: ["https://api.demo-api.globex.localhost"]
+```
+
+That is `examples/demo/demo-api/.den.yml`; the other demo repos are in
+[`examples/demo/`](../examples/demo/).
+
+## What it does
+
+- **Workspaces.** A workspace is a set of repos. Each is either
+  _dev-managed_ (your checkout, your branch) or _managed_ (cloned by Den and
+  kept on a tracking branch).
+- **Derived dependency graph.** Start and stop order comes from real signals in
+  each repo — SDK imports, `*_URL` env vars, IaC references, event rules,
+  readiness probes — tuned in config with `graph.aliases`, `graph.edges` and
+  an optional shared local-infra repo (`graph.infra`).
+- **Local HTTPS edge.** One local proxy routes `https://<route>.<domain>` to
+  each service, with an optional project CA.
+- **Test pillars.** `smoke`, `browser` (synthetic Playwright), `api`,
+  `journeys` (agent-driven), `perf` (k6), `security` (OWASP ZAP against hosts
+  you own) and `suites` (a repo's own commands).
+- **Releases.** A release view over the repos and deploy workflows your config
+  lists.
+- **Agents and sessions.** `sessions start` runs a terminal that outlives the
+  web server; `agents start` runs a persona (Den ships a default pack) in a
+  workspace's checkout, with an MCP server pinned to that workspace and a
+  token of its own. The web UI's Agents tab lists them and opens their
+  terminals.
+- **Browser sign-in beyond loopback.** On localhost no route needs a sign-in.
+  Through the edge or on a non-loopback bind, every route needs one:
+  `<cli> web login` prints a one-time link (`web open` opens it).
+- **Web UI and CLI** over the same state.
+
+## Strategies
+
+Concerns that vary by org are strategies selected in config, never hard-wired:
+
+| Concern          | Built-in choices                        | Chosen in                                                                                                            |
+| ---------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| Secrets backend  | `none`, `env`, `doppler`, `1password`   | `secrets.provider` in the org config; per engineer in `config/local/user.yml`; per shell `<PREFIX>_SECRETS_PROVIDER` |
+| Test-user tokens | `local-jwt`, `cognito`, `auth0`, `none` | `auth.provider` in `config/environments/<env>.json`                                                                  |
+
+A new secrets backend implements `SecretsProvider`
+(`src/shared/secrets/types.ts`) and registers as a strategy
+(`src/shared/secrets/strategies.ts`); a distribution needs no store at all
+(`none`, see "Secrets" in `docs/distributions.md`). A new identity provider implements a token
+provider in `src/shared/auth/token-providers/`.
+
+## CLI
+
+```bash
+den up [repo]          # start the repo's derived dependency closure (-x deps only, -n dry run)
+den down [repo]        # stop it cleanly (--with-deps: and what it sits on)
+den restart [svc...]   # restart services (-A <app> for a whole application)
+den status             # service health for the active workspace
+den apps               # Org > Application > Repo > Services
+den graph [repo]       # the derived dependency graph
+den logs [repo]        # tail a repo's local logs
+den use-local [repo]   # use your checkout · use-managed [repo] to switch back
+den workspace list     # workspaces (activate · deactivate · use · create · delete)
+den run                # run test suites (interactive, or with options)
+den web                # the web UI (open · login · sessions · logout · token)
+den sessions list      # terminals that outlive the web server (start · attach · kill)
+den agents list -w ws  # a workspace's agents (start · stop · resume · personas)
+den doctor             # the strategies in use and whether each can work (--probe)
+den --help             # everything else
+```
+
+`up`, `down`, `restart` and `setup` take `-w <workspace>`. Without it, a
+service you name is found in the focused workspace first, then across the
+other active workspaces; when it is in several, the error lists the `-w`
+command for each.
+
+In a distribution the command is that distribution's `cli` name.
+
+## Developing Den
+
+```bash
+npm ci
+npm run typecheck
+npm run lint
+npm test
+DEN_ORG_NAMES_FILE=<patterns file> node scripts/org-name-gate.mjs
+```
+
+CI runs the same gates. The org-name gate fails the build when any file names
+an organisation, product, host or account; its patterns are kept out of this
+repo (a CI secret) so the list itself is never published. See
+[CONTRIBUTING.md](../CONTRIBUTING.md).
+
+## License
+
+[MIT](../LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monster-orange/den",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Den: a local multi-repo dev orchestrator, HTTPS edge and E2E harness",
   "type": "module",
   "bin": {
@@ -62,6 +62,8 @@
     "@modelcontextprotocol/sdk": "1.32.1",
     "@playwright/test": "^1.61.1",
     "@slack/webhook": "^7.0.2",
+    "@xterm/addon-fit": "0.11.0",
+    "@xterm/xterm": "6.0.0",
     "ajv": "^8.12.0",
     "ajv-formats": "^2.1.1",
     "auth0": "^4.3.1",

package/src/shared/actor-token.ts

@@ -0,0 +1,275 @@
+/**
+ * SEC-1c (SEC-1 spec §5): an agent's actor token.
+ *
+ * `agents start` (and resume) mints `den_at_<43 b64url>`: 32 random bytes,
+ * handed to the agent's session as DEN_ACTOR_TOKEN and to nothing else.
+ * The state dir keeps only its sha256 (`actor-tokens.json`, 0600, the dir
+ * 0700), with what it proves:
+ *
+ *   { actor: "agent:<id>", workspace, grants, session: { name, id } }
+ *
+ * - One live token per agent: minting another (a resume, a restart)
+ *   revokes the old one, so it stops working at once.
+ * - Revoked when the agent stops (`agents stop`, the page's Stop), and when
+ *   its session ends: a token verifies only while the session it was minted
+ *   for is listed as running in the session host's own record
+ *   (`sessions/<id>.json`); an ended one's token is removed when presented.
+ * - It never derives from web.secret, so it proves nothing about the
+ *   person. `web logout --all` (the "something leaked" button, SEC-1
+ *   §6c.2) revokes every token as well as rotating the secret: each record
+ *   is kept, marked `revokedAt`, so a running agent's next call is told
+ *   `token_revoked` (restart or resume it) rather than a bare 401. Minting
+ *   the agent's next token, or its session's end, drops the record.
+ *
+ * Nothing here prints or logs a token.
+ */
+import { createHash, randomBytes } from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+import { AGENT_ACTOR_RE, WORKSPACE_NAME_RE } from "./agent-actor.js";
+import { sessionPaths } from "./sessions/paths.js";
+
+export const ACTOR_TOKEN_PREFIX = "den_at_";
+/** The agent's session carries its token here (AG spec §5a-env). */
+export const ACTOR_TOKEN_ENV = "DEN_ACTOR_TOKEN";
+/** A person's token in an env: never forwarded to any session. */
+export const PERSON_TOKEN_ENV = "DEN_PERSON_TOKEN";
+export const ACTOR_TOKENS_FILE = "actor-tokens.json";
+
+const TOKEN_RE = /^den_at_[A-Za-z0-9_-]{43}$/;
+/** web-secret.ts's PERSON_TOKEN_PREFIX and WEB_SECRET_FILE (it imports this module). */
+const PERSON_PREFIX = "den_pt_";
+const SECRET_FILE = "web.secret";
+
+export interface ActorTokenRecord {
+  actor: `agent:${string}`;
+  workspace: string;
+  /** The agent's grants (agents.<id>.grants) when it was minted. */
+  grants: string[];
+  /** The session it was minted for: its name, and its id once started. */
+  session: { name: string; id?: string };
+  /** ISO 8601. */
+  createdAt: string;
+  /** ISO 8601: revoked by `web logout --all`. A revoked token never verifies. */
+  revokedAt?: string;
+}
+
+interface StoreFile {
+  v: 1;
+  /** sha256(token), hex → what it proves. */
+  tokens: Record<string, ActorTokenRecord>;
+}
+
+export function actorTokensPath(stateDir: string): string {
+  return path.join(stateDir, ACTOR_TOKENS_FILE);
+}
+
+/** The token's key in the store: sha256, hex. */
+export function actorTokenKey(token: string): string {
+  return createHash("sha256").update(token).digest("hex");
+}
+
+/** Shaped like an actor token (says nothing about whether it is live). */
+export function isActorTokenShape(v: string | undefined): v is string {
+  return typeof v === "string" && TOKEN_RE.test(v);
+}
+
+function load(stateDir: string): StoreFile {
+  try {
+    const raw = JSON.parse(
+      fs.readFileSync(actorTokensPath(stateDir), "utf-8"),
+    ) as Partial<StoreFile>;
+    const tokens =
+      raw.tokens && typeof raw.tokens === "object" && !Array.isArray(raw.tokens)
+        ? raw.tokens
+        : {};
+    return { v: 1, tokens };
+  } catch {
+    return { v: 1, tokens: {} };
+  }
+}
+
+function save(stateDir: string, data: StoreFile): void {
+  fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+  const file = actorTokensPath(stateDir);
+  const tmp = `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+  fs.chmodSync(tmp, 0o600);
+  fs.renameSync(tmp, file);
+}
+
+/**
+ * A fresh token for agent `agentId`, its hash recorded, every older token
+ * of the same agent revoked. The token itself is returned once and never
+ * stored.
+ */
+export function mintActorToken(
+  stateDir: string,
+  o: {
+    agentId: string;
+    workspace: string;
+    grants?: readonly string[];
+    sessionName: string;
+  },
+): { token: string; key: string } {
+  const actor = `agent:${o.agentId}` as const;
+  if (!AGENT_ACTOR_RE.test(actor))
+    throw new Error(`"${o.agentId}" is not an agent id`);
+  if (!WORKSPACE_NAME_RE.test(o.workspace))
+    throw new Error(`"${o.workspace}" is not a workspace name`);
+  const token = ACTOR_TOKEN_PREFIX + randomBytes(32).toString("base64url");
+  const key = actorTokenKey(token);
+  const data = load(stateDir);
+  for (const [k, r] of Object.entries(data.tokens))
+    if (r.actor === actor) delete data.tokens[k];
+  data.tokens[key] = {
+    actor,
+    workspace: o.workspace,
+    grants: (o.grants ?? []).filter((g) => WORKSPACE_NAME_RE.test(g)),
+    session: { name: o.sessionName },
+    createdAt: new Date().toISOString(),
+  };
+  save(stateDir, data);
+  return { token, key };
+}
+
+/** Bind a minted token to the session id the host gave its session. */
+export function bindActorSession(
+  stateDir: string,
+  key: string,
+  sessionId: string,
+): void {
+  const data = load(stateDir);
+  const rec = data.tokens[key];
+  if (!rec) return;
+  rec.session = { ...rec.session, id: sessionId };
+  save(stateDir, data);
+}
+
+/** Revoke one token (by its key). */
+export function revokeActorToken(stateDir: string, key: string): boolean {
+  const data = load(stateDir);
+  if (!data.tokens[key]) return false;
+  delete data.tokens[key];
+  save(stateDir, data);
+  return true;
+}
+
+/** Revoke every token of agent `agentId`; how many there were. */
+export function revokeAgentTokens(stateDir: string, agentId: string): number {
+  const data = load(stateDir);
+  const actor = `agent:${agentId}`;
+  let n = 0;
+  for (const [k, r] of Object.entries(data.tokens))
+    if (r.actor === actor) {
+      delete data.tokens[k];
+      n++;
+    }
+  if (n) save(stateDir, data);
+  return n;
+}
+
+/**
+ * Revoke every agent's token (`web logout --all`, SEC-1 §6c.2): each record
+ * is marked revoked, so its agent learns why. How many were live.
+ */
+export function revokeAllActorTokens(stateDir: string): number {
+  const data = load(stateDir);
+  const now = new Date().toISOString();
+  let n = 0;
+  for (const r of Object.values(data.tokens))
+    if (!r.revokedAt) {
+      r.revokedAt = now;
+      n++;
+    }
+  if (n) save(stateDir, data);
+  return n;
+}
+
+/**
+ * The agents whose token `web logout --all` revoked and whose record is
+ * still kept (their session still runs): the Agents tab marks them, so a
+ * person knows to restart or resume them (AG-4a-term). Ids only.
+ */
+export function revokedAgentIds(stateDir: string): Set<string> {
+  const out = new Set<string>();
+  for (const r of Object.values(load(stateDir).tokens))
+    if (r.revokedAt && AGENT_ACTOR_RE.test(r.actor))
+      out.add(r.actor.slice("agent:".length));
+  return out;
+}
+
+/** What a presented token was minted as, live or not; null when unknown. */
+export function lookupActorToken(
+  stateDir: string,
+  token: string,
+): ActorTokenRecord | null {
+  if (!isActorTokenShape(token)) return null;
+  return load(stateDir).tokens[actorTokenKey(token)] ?? null;
+}
+
+/** Whether the session host lists session `id` as running (its own record). */
+export function sessionRunning(stateDir: string, id: string): boolean {
+  if (!/^[A-Za-z0-9_-]{1,128}$/.test(id)) return false;
+  try {
+    const rec = JSON.parse(
+      fs.readFileSync(
+        path.join(sessionPaths(stateDir).dir, `${id}.json`),
+        "utf-8",
+      ),
+    ) as { exited?: unknown };
+    return rec.exited !== true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * What a presented token proves: its record; `"revoked"` when `web logout
+ * --all` revoked it and its session still runs (the agent is told to
+ * restart or resume); or null: unknown, not yet bound to a session, or its
+ * session has ended (then its record is removed here).
+ */
+export function checkActorToken(
+  stateDir: string,
+  token: string,
+): ActorTokenRecord | "revoked" | null {
+  const rec = lookupActorToken(stateDir, token);
+  if (!rec?.session.id) return null;
+  if (!sessionRunning(stateDir, rec.session.id)) {
+    try {
+      revokeActorToken(stateDir, actorTokenKey(token));
+    } catch {
+      /* a read-only state dir: still refused */
+    }
+    return null;
+  }
+  return rec.revokedAt ? "revoked" : rec;
+}
+
+/** The record a presented token proves, or null (checkActorToken, revoked or not). */
+export function verifyActorToken(
+  stateDir: string,
+  token: string,
+): ActorTokenRecord | null {
+  const r = checkActorToken(stateDir, token);
+  return r === "revoked" ? null : r;
+}
+
+/**
+ * A person's credential in an env (SEC-1 §5): DEN_PERSON_TOKEN, a value
+ * shaped like a person token, or a value that names a web.secret file.
+ * No session Den starts ever gets one, and `--keep-env` can't forward one.
+ */
+export function isPersonCredentialEnv(
+  name: string,
+  value: string | undefined,
+): boolean {
+  if (name === PERSON_TOKEN_ENV) return true;
+  if (value === undefined) return false;
+  const v = value.trim();
+  if (v.includes(PERSON_PREFIX)) return true;
+  return v
+    .split(/[:;,\s]+/)
+    .some((part) => path.basename(part.replace(/[/\\]+$/, "")) === SECRET_FILE);
+}

package/src/shared/agent-actor.ts

@@ -43,6 +43,11 @@ export interface AgentInfo {
 
 export interface AgentActor extends AgentInfo {
   kind: "agent";
+  /**
+   * SEC-1c: set when this came from headers the caller set, not from an
+   * agent's actor token. The audit keeps it as a claim, never as the actor.
+   */
+  unverified?: true;
 }
 
 /** null: a person in the web UI (no agent headers). */
@@ -75,7 +80,11 @@ export function agentAuditHeaders(info: AgentInfo): Record<string, string> {
   };
 }
 
-/** The actor an incoming request names, or null for a person in the UI. */
+/**
+ * The actor an incoming request's headers claim, or null. SEC-1c: a claim,
+ * never the audit actor; the server's auditActorOf (request-guard.ts)
+ * takes the actor from the credential and keeps this as unverified.
+ */
 export function actorFromHeaders(
   headers: IncomingHttpHeaders | Record<string, string | undefined>,
 ): Actor {
@@ -107,6 +116,7 @@ export function actorLabel(actor: AgentActor): string {
   const ws = actor.workspace ? `workspace ${actor.workspace}, ` : "";
   return (
     `${who} ${actor.client} ${actor.clientVersion} ` +
-    `(${ws}mcp pid ${actor.mcpPid ?? "?"}, session ${actor.session || "?"})`
+    `(${ws}mcp pid ${actor.mcpPid ?? "?"}, session ${actor.session || "?"})` +
+    (actor.unverified ? " (unverified)" : "")
   );
 }

package/src/shared/agents/den-claude.ts

@@ -9,6 +9,12 @@
  *   workspace; --strict-mcp-config keeps any other MCP server out, so the
  *   agent acts only through Den (§1).
  * - The role prompt is appended to Claude Code's own system prompt.
+ * - Den's state dir is denied to the agent (SEC-1 §6c.1): a settings file
+ *   (--settings, 0600) whose `permissions.deny` lists Read and Bash rules
+ *   (any command naming the path) for `<state>/web.secret` and
+ *   `<state>/sessions/**`. It binds a
+ *   cooperating agent only: the agent runs as the same OS user, so nothing
+ *   stops one that ignores its permission config from reading them.
  * - Each launch picks a fresh conversation id (--session-id); resume
  *   continues it with --resume <id>, in the same cwd, with the same MCP.
  * - Permission prompts stay in the terminal (approvals: "terminal"):
@@ -98,6 +104,81 @@ function detect(env: NodeJS.ProcessEnv = process.env): RuntimeDetect {
   return version ? { available: true, version } : { available: true };
 }
 
+/**
+ * Claude Code `permissions.deny` rules that keep a cooperating agent out of
+ * Den's credentials (SEC-1 §6c.1): web.secret and the session host's
+ * records.
+ *
+ * - Read: absolute paths (`//…` in Claude Code's rule syntax).
+ * - Bash, in Claude Code's documented wildcard form: `*` matches any run of
+ *   characters, at any position, and a rule matches a command (each part
+ *   of a compound one) whole. `Bash(*<path>*)` denies any command that names
+ *   the path, whatever the program (cat, head, cp, base64) and whether it is
+ *   quoted ("…" or '…' still contain it). The legacy prefix form,
+ *   `Bash(cat <path>:*)`, didn't match a bare `cat <path>` on Claude Code
+ *   2.1.x (it asked for approval instead of denying: a dogfood finding), so
+ *   it is kept only for older versions, after the wildcard rules.
+ * - The readers in BASH_READERS (cat, head, tail, …) by name as well. This
+ *   binds a cooperating agent only, and no list names every reader: the
+ *   boundary is the server's token rules (SEC-1 §5), never these.
+ * - The same path as a shell writes it from `home`: `~/…` and `$HOME/…`,
+ *   `${HOME}/…`, and, when the path has a space, with each space
+ *   backslash-escaped.
+ */
+export function stateDirDenyRules(stateDir: string, home?: string): string[] {
+  const abs = path.resolve(stateDir);
+  const secret = path.join(abs, "web.secret");
+  const sessions = path.join(abs, "sessions");
+  const spellings = (p: string): string[] => {
+    const out = [p];
+    if (home) {
+      const h = path.resolve(home);
+      if (p.startsWith(h + path.sep)) {
+        const rel = p.slice(h.length + 1);
+        out.push(`~/${rel}`, `$HOME/${rel}`, "${HOME}/" + rel);
+      }
+    }
+    for (const x of [...out])
+      if (x.includes(" ")) out.push(x.replace(/ /g, "\\ "));
+    return [...new Set(out)];
+  };
+  const targets = [
+    ...spellings(secret).map((p) => `${p}*`),
+    ...spellings(sessions).map((p) => `${p}/*`),
+  ];
+  return [
+    `Read(/${secret})`,
+    `Read(/${sessions}/**)`,
+    // Any command naming the path, whatever the program.
+    ...targets.map((t) => `Bash(*${t})`),
+    // The common readers by name too, should a version match a leading
+    // wildcard differently. A deny list can't name every reader: the
+    // boundary is the server's token rules (SEC-1 §5), not these.
+    ...BASH_READERS.flatMap((r) => targets.map((t) => `Bash(${r} *${t})`)),
+    `Bash(cat ${secret}:*)`,
+    `Bash(cat ${sessions}/:*)`,
+  ];
+}
+
+/** The readers named in the Bash deny rules (stateDirDenyRules). */
+export const BASH_READERS = [
+  "cat",
+  "head",
+  "tail",
+  "less",
+  "more",
+  "xxd",
+  "od",
+  "strings",
+  "base64",
+  "cp",
+] as const;
+
+/** The settings file den-claude passes with --settings. */
+export function settingsPath(input: Pick<LaunchInput, "filesDir">): string {
+  return path.join(input.filesDir, "settings.json");
+}
+
 /** The flags every run shares: Den's MCP only, the model, the role prompt. */
 function common(input: LaunchInput): {
   argv: string[];
@@ -106,11 +187,13 @@ function common(input: LaunchInput): {
 } {
   const file = mcpConfigPath(input);
   const mode = permissionMode(input);
+  const settings = input.stateDir ? settingsPath(input) : null;
   return {
     argv: [
       "--mcp-config",
       file,
       "--strict-mcp-config",
+      ...(settings ? ["--settings", settings] : []),
       "--permission-mode",
       mode,
       ...(input.model ? ["--model", input.model] : []),
@@ -122,7 +205,22 @@ function common(input: LaunchInput): {
         input.mcp.name,
       ),
     ],
-    files: { [file]: mcpConfigJson(input.mcp) },
+    files: {
+      [file]: mcpConfigJson(input.mcp),
+      ...(settings && input.stateDir
+        ? {
+            [settings]: `${JSON.stringify(
+              {
+                permissions: {
+                  deny: stateDirDenyRules(input.stateDir, input.env?.HOME),
+                },
+              },
+              null,
+              2,
+            )}\n`,
+          }
+        : {}),
+    },
     warnings:
       mode === "bypassPermissions"
         ? [

package/src/shared/agents/runtime.ts

@@ -51,6 +51,13 @@ export interface LaunchInput {
   mcp: AgentMcp;
   /** A directory of this agent's own (0700) for the files a runtime writes. */
   filesDir: string;
+  /**
+   * Den's own state dir (web.secret, the session records). A runtime adds
+   * deny rules for it to the agent's own permission config (SEC-1 §6c.1):
+   * that binds a cooperating agent only, since an agent runs as the same OS
+   * user and could read the files itself.
+   */
+  stateDir?: string;
   /**
    * The caller's environment, for finding the runtime's CLI on PATH. The
    * agent does not get it: it starts from an allowlist (sessions/env.ts),

package/src/shared/agents/runtimes.ts

@@ -5,6 +5,7 @@
 import { denClaude } from "./den-claude.js";
 import { generic } from "./generic.js";
 import { allScrubEnv, registerRuntime, type Runtime } from "./runtime.js";
+import { ACTOR_TOKEN_ENV } from "../actor-token.js";
 import { AGENT_ACTOR_ENV, buildSessionEnv } from "../sessions/env.js";
 
 registerRuntime(denClaude);
@@ -27,13 +28,16 @@ export {
 /**
  * An agent's session env, as `agents start` builds it and `doctor --probe`
  * checks it: the allowlist, the runtime's passthrough and launch env, Den's
- * marker (DEN_AGENT=agent:<id>), then every runtime's scrubEnv.
+ * markers (DEN_AGENT=agent:<id>, and SEC-1c's DEN_ACTOR_TOKEN when one was
+ * minted), then every runtime's scrubEnv and any person credential.
  */
 export function agentSessionEnv(
   caller: NodeJS.ProcessEnv,
   rt: Pick<Runtime, "envPassthrough">,
   launch: Record<string, string>,
   agentId: string,
+  /** SEC-1c: the agent's actor token (`agents start` mints it; the probe has none). */
+  actorToken?: string,
 ): Record<string, string> {
   return buildSessionEnv({
     caller,
@@ -41,7 +45,10 @@ export function agentSessionEnv(
     launch,
     // The seam for a persona's or runtime's declared env: none yet.
     extra: {},
-    den: { [AGENT_ACTOR_ENV]: `agent:${agentId}` },
+    den: {
+      [AGENT_ACTOR_ENV]: `agent:${agentId}`,
+      ...(actorToken ? { [ACTOR_TOKEN_ENV]: actorToken } : {}),
+    },
     scrub: allScrubEnv(),
   });
 }