@superjackfruitlabs/salaam 0.0.4 → 0.0.5

package/src/approval-rules.ts

@@ -0,0 +1,360 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import type { Store } from './store.js';
+import { object, ServiceError } from './protocol.js';
+
+/**
+ * Approval rules for desk sessions (operator plan 2026-10-31, phase 2a), in the manner of OpenCode:
+ * allow, ask or deny by tool, command pattern and path glob. Deny beats ask, ask beats allow, and with
+ * no matching rule the answer is ask.
+ *
+ * Commands are matched on their parsed words, never as text, so an `npm test` rule cannot carry
+ * `npm test; rm -rf /`: anything a shell would reinterpret (chaining, pipes, redirection, expansion,
+ * globs, assignments, quoting it cannot close) makes the command unreadable, and an unreadable command
+ * can only be denied, never allowed.
+ *
+ * Rules live in Salaam's own state, not in the repository: the agent can write to its workspace, so
+ * a rules file there would let it grant itself permissions. Session rules last for one session; repo
+ * rules are kept against the repository's real path and apply to every desk session on it; user rules
+ * come from a file in the user's config directory, which the default sandbox cannot write.
+ */
+export type RuleEffect = 'allow' | 'ask' | 'deny';
+export type RuleTool = 'command' | 'edit' | 'any';
+export type RuleSource = 'session' | 'repo' | 'user';
+export interface ApprovalRule {
+  effect: RuleEffect;
+  tool: RuleTool;
+  /** Command words; a word may contain `*`, and a final lone `*` takes any further words. */
+  command?: string;
+  /** Project-relative globs for edits: `*` within one path segment, `**` across segments. */
+  paths?: string[];
+}
+export interface StoredRule extends ApprovalRule {
+  id: string;
+  source: RuleSource;
+}
+export type RuleRequest =
+  { tool: 'command'; argv: string[] | null } | { tool: 'edit'; paths: string[] };
+
+const SHELL_SPECIAL = /[;&|<>`$(){}\\\n\r*?[\]~!#]/;
+const PRIVATE_PART = /^(\.|credentials$|secrets$)/;
+
+/** The command's words, or null when a shell would read it as more than plain words. */
+export function commandArgv(command: string): string[] | null {
+  const words: string[] = [];
+  let word = '',
+    inWord = false;
+  for (let i = 0; i < command.length; i++) {
+    const ch = command[i]!;
+    if (ch === "'") {
+      const end = command.indexOf("'", i + 1);
+      if (end < 0) return null;
+      word += command.slice(i + 1, end);
+      inWord = true;
+      i = end;
+    } else if (ch === '"') {
+      const end = command.indexOf('"', i + 1);
+      if (end < 0) return null;
+      const inner = command.slice(i + 1, end);
+      if (/[$`\\]/.test(inner)) return null;
+      word += inner;
+      inWord = true;
+      i = end;
+    } else if (ch === ' ' || ch === '\t') {
+      if (inWord) words.push(word);
+      word = '';
+      inWord = false;
+    } else if (SHELL_SPECIAL.test(ch)) return null;
+    else {
+      word += ch;
+      inWord = true;
+    }
+  }
+  if (inWord) words.push(word);
+  // A leading NAME=value is an environment assignment, not a command word.
+  if (!words.length || /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0]!)) return null;
+  return words;
+}
+function patternWords(pattern: string): string[] {
+  const words = pattern.trim().split(/\s+/);
+  if (!pattern.trim() || words.some((w) => /[;&|<>`$(){}\\'"!#~?[\]]/.test(w)))
+    throw new ServiceError(
+      'invalid_rule',
+      'A command rule is plain words; a word may use *, and a final * takes any further words',
+    );
+  return words;
+}
+const wordRe = (w: string) =>
+  new RegExp(
+    '^' +
+      w
+        .split('*')
+        .map((p) => p.replace(/[.+^${}()|[\]\\]/g, '\\$&'))
+        .join('.*') +
+      '$',
+  );
+function commandMatches(pattern: string, argv: string[]): boolean {
+  const words = patternWords(pattern);
+  const rest = words[words.length - 1] === '*';
+  const fixed = rest ? words.slice(0, -1) : words;
+  if (rest ? argv.length < fixed.length : argv.length !== fixed.length) return false;
+  return fixed.every((w, i) => wordRe(w).test(argv[i]!));
+}
+/** A project-relative glob as a regex: `**` spans segments, `*` stays within one. */
+function globRe(glob: string): RegExp {
+  let re = '';
+  for (let i = 0; i < glob.length; i++) {
+    if (glob.startsWith('**/', i)) {
+      re += '(?:.*/)?';
+      i += 2;
+    } else if (glob.startsWith('/**', i) && i + 3 === glob.length) {
+      re += '(?:/.*)?';
+      i += 2;
+    } else if (glob.startsWith('**', i)) {
+      re += '.*';
+      i += 1;
+    } else if (glob[i] === '*') re += '[^/]*';
+    else re += glob[i]!.replace(/[.+^${}()|[\]\\?]/g, '\\$&');
+  }
+  return new RegExp('^' + re + '$');
+}
+const pathMatches = (globs: string[], path: string) => globs.some((g) => globRe(g).test(path));
+
+export function validateRule(value: unknown): ApprovalRule {
+  const input = object(value);
+  if (Object.keys(input).some((k) => !['effect', 'tool', 'command', 'paths'].includes(k)))
+    throw new ServiceError('invalid_rule', 'A rule has effect, tool, and command or paths only');
+  if (!['allow', 'ask', 'deny'].includes(String(input.effect)))
+    throw new ServiceError('invalid_rule', 'A rule effect is allow, ask or deny');
+  if (!['command', 'edit', 'any'].includes(String(input.tool)))
+    throw new ServiceError('invalid_rule', 'A rule tool is command, edit or any');
+  const rule: ApprovalRule = { effect: input.effect as RuleEffect, tool: input.tool as RuleTool };
+  if (input.command !== undefined) {
+    if (typeof input.command !== 'string' || input.command.length > 512 || input.tool === 'edit')
+      throw new ServiceError('invalid_rule', 'Only command rules take a command pattern');
+    patternWords(input.command);
+    rule.command = input.command.trim().split(/\s+/).join(' ');
+  }
+  if (input.paths !== undefined) {
+    const paths = input.paths;
+    if (
+      input.tool === 'command' ||
+      !Array.isArray(paths) ||
+      !paths.length ||
+      paths.length > 32 ||
+      paths.some(
+        (p) =>
+          typeof p !== 'string' ||
+          p.length > 512 ||
+          p.startsWith('/') ||
+          /[\x00-\x1f\x7f\\]/.test(p) ||
+          p.split('/').some((part) => !part || part === '..' || PRIVATE_PART.test(part)),
+      )
+    )
+      throw new ServiceError(
+        'invalid_rule',
+        'Edit rules take up to 32 project-relative globs; no absolute paths, traversal or private paths',
+      );
+    rule.paths = [...(paths as string[])];
+  }
+  if (rule.tool === 'edit' && !rule.paths)
+    throw new ServiceError('invalid_rule', 'An edit rule names the paths it covers');
+  return rule;
+}
+
+/** The deciding rule for a request: deny beats ask beats allow; no match asks. */
+export function evaluateRules(
+  rules: StoredRule[],
+  request: RuleRequest,
+): { effect: RuleEffect; rule?: StoredRule } {
+  const matching = rules.filter((r) => {
+    if (r.tool !== 'any' && r.tool !== request.tool) return false;
+    if (request.tool === 'command') {
+      if (r.paths) return false;
+      if (!r.command) return r.effect === 'deny' || request.argv !== null;
+      return request.argv !== null && commandMatches(r.command, request.argv);
+    }
+    if (!r.paths) return r.tool === 'any' && !r.command;
+    return r.effect === 'allow'
+      ? request.paths.length > 0 && request.paths.every((p) => pathMatches(r.paths!, p))
+      : request.paths.some((p) => pathMatches(r.paths!, p));
+  });
+  for (const effect of ['deny', 'ask', 'allow'] as const) {
+    const rule = matching.find((r) => r.effect === effect);
+    if (rule) return { effect, rule };
+  }
+  return { effect: 'ask' };
+}
+
+export function defaultUserRulesFile(env = process.env): string {
+  return (
+    env.SALAAM_PERMISSIONS_FILE ||
+    join(env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'salaam', 'permissions.json')
+  );
+}
+
+export class ApprovalRules {
+  constructor(
+    readonly store: Store,
+    readonly userFile: string = defaultUserRulesFile(),
+  ) {
+    store.db.exec(`CREATE TABLE IF NOT EXISTS approval_rules(
+      id TEXT PRIMARY KEY NOT NULL,
+      scope TEXT NOT NULL CHECK(scope IN ('session','repo')),
+      session_id TEXT,
+      root TEXT NOT NULL,
+      rule TEXT NOT NULL,
+      created_at INTEGER NOT NULL)`);
+  }
+  /** Whether rules apply: only desk sessions, never host-managed (AgentPod) or child work. */
+  applies(session: string): boolean {
+    if (!this.store.localCoding(session)) return false;
+    const has = (sql: string) => {
+      try {
+        return !!this.store.db.prepare(sql).get(session);
+      } catch {
+        return false;
+      }
+    };
+    return (
+      !has('SELECT 1 FROM agentpod_admissions WHERE session_id=?') &&
+      !has('SELECT 1 FROM child_tasks WHERE child_session=?')
+    );
+  }
+  private userRules(): { rules: StoredRule[]; problem?: string } {
+    let text: string;
+    try {
+      text = readFileSync(this.userFile, 'utf8');
+    } catch {
+      return { rules: [] };
+    }
+    try {
+      const doc = object(JSON.parse(text));
+      if (doc.version !== 1 || !Array.isArray(doc.rules))
+        throw new Error('expected {"version": 1, "rules": [...]}');
+      return {
+        rules: doc.rules.map((r, i) => ({
+          ...validateRule(r),
+          id: 'user:' + i,
+          source: 'user' as const,
+        })),
+      };
+    } catch (error) {
+      return {
+        rules: [],
+        problem: `${this.userFile} is ignored: ${error instanceof Error ? error.message : 'unreadable'}`,
+      };
+    }
+  }
+  list(session: string): StoredRule[] {
+    const root = this.store.session(session).cwd;
+    const stored = this.store.db
+      .prepare(
+        "SELECT id,scope,rule FROM approval_rules WHERE (scope='session' AND session_id=?) OR (scope='repo' AND root=?) ORDER BY created_at,rowid",
+      )
+      .all(session, root) as { id: string; scope: RuleSource; rule: string }[];
+    return [
+      ...stored.map((r) => ({
+        ...(JSON.parse(r.rule) as ApprovalRule),
+        id: r.id,
+        source: r.scope,
+      })),
+      ...this.userRules().rules,
+    ];
+  }
+  problems(session: string): string[] {
+    void session;
+    const problem = this.userRules().problem;
+    return problem ? [problem] : [];
+  }
+  add(session: string, scope: 'session' | 'repo', value: unknown, request: string): StoredRule {
+    const rule = validateRule(value);
+    if (!this.applies(session))
+      throw new ServiceError(
+        'rules_unavailable',
+        'Approval rules apply only to desk coding sessions',
+      );
+    return this.store.request(
+      'local-operator',
+      request,
+      { kind: 'approval-rule', session, scope, rule },
+      () => {
+        const id = randomUUID();
+        this.store.db
+          .prepare(
+            'INSERT INTO approval_rules(id,scope,session_id,root,rule,created_at) VALUES(?,?,?,?,?,?)',
+          )
+          .run(
+            id,
+            scope,
+            scope === 'session' ? session : null,
+            this.store.session(session).cwd,
+            JSON.stringify(rule),
+            Date.now(),
+          );
+        this.store.event(session, 'approval_rule.added', { id, scope, rule });
+        return { ...rule, id, source: scope };
+      },
+    );
+  }
+  remove(session: string, id: string): void {
+    const root = this.store.session(session).cwd;
+    const done = this.store.db
+      .prepare(
+        "DELETE FROM approval_rules WHERE id=? AND ((scope='session' AND session_id=?) OR (scope='repo' AND root=?))",
+      )
+      .run(id, session, root);
+    if (!done.changes)
+      throw new ServiceError('rule_not_found', 'No such rule for this session or repository');
+    this.store.event(session, 'approval_rule.removed', { id });
+  }
+  /** The rule an approved operation stands for: the exact command words, or the exact edited paths. */
+  ruleFor(args: { action: string; command?: string; edits?: { path: string }[] }): ApprovalRule {
+    if (args.action === 'command') {
+      const argv = commandArgv(args.command ?? '');
+      if (!argv)
+        throw new ServiceError(
+          'invalid_rule',
+          'This command uses shell features a rule cannot match safely; approve it once instead',
+        );
+      const quote = (w: string) =>
+        /^[A-Za-z0-9_@%+=:,./-]+$/.test(w) && !w.includes('*') ? w : null;
+      if (argv.some((w) => quote(w) === null))
+        throw new ServiceError(
+          'invalid_rule',
+          'This command has words a rule cannot spell exactly; approve it once instead',
+        );
+      return validateRule({ effect: 'allow', tool: 'command', command: argv.join(' ') });
+    }
+    if (args.action === 'edit' && args.edits?.length)
+      return validateRule({ effect: 'allow', tool: 'edit', paths: args.edits.map((e) => e.path) });
+    throw new ServiceError('invalid_rule', 'Only local commands and edits can become rules');
+  }
+  addFromOperation(
+    session: string,
+    operation: string,
+    scope: 'session' | 'repo',
+    request: string,
+  ): StoredRule {
+    const row = this.store.db
+      .prepare('SELECT args,session_id FROM local_calls WHERE operation_id=?')
+      .get(operation) as { args: string; session_id: string } | undefined;
+    if (!row || row.session_id !== session)
+      throw new ServiceError(
+        'rule_not_found',
+        'That request is not a local command or edit in this session',
+      );
+    return this.add(session, scope, this.ruleFor(JSON.parse(row.args)), request);
+  }
+}
+
+/** Why a reviewed request can only be approved once: a command with shell features (pipes,
+ * redirects, substitutions) can never become an approval rule. Undefined when a rule is possible. */
+export function onceOnlyReason(value: string): string | undefined {
+  const command = /\nCommand:\n([\s\S]*)$/.exec(value)?.[1];
+  return command !== undefined && commandArgv(command) === null
+    ? 'This command uses shell features (pipes, redirects, substitutions), so it cannot become a rule. Approve it once or deny it.'
+    : undefined;
+}

package/src/attach.ts

@@ -29,6 +29,7 @@ interface Pending {
   expected_revision: number;
   text: string;
   continues_attempt_id?: string;
+  confirm_sensitive?: boolean;
   command?:
     | {
         kind: 'decision';
@@ -74,7 +75,7 @@ export class Outbox {
     renameSync(temporary, path);
     syncDirectory(this.dir);
   }
-  enqueue(text: string, revision: number, continues?: string): Pending {
+  enqueue(text: string, revision: number, continues?: string, confirmSensitive = false): Pending {
     if (!text.trim() || text.length > 256 * 1024 || text.trimStart().startsWith('/'))
       throw new Error('Enter a plain instruction of at most 256 Ki characters');
     const created = this.records().reduce(
@@ -87,6 +88,7 @@ export class Outbox {
       expected_revision: revision,
       text,
       ...(continues ? { continues_attempt_id: continues } : {}),
+      ...(confirmSensitive ? { confirm_sensitive: true } : {}),
     };
     this.save(record);
     return record;
@@ -228,6 +230,7 @@ export class Outbox {
               'approval_mismatch',
               'binding_changed',
               'attempt_settled',
+              'sensitive_attachment',
             ].includes(error.code) ||
               (record.command && error.code === 'not_found') ||
               (['task', 'job'].includes(record.command?.kind ?? '') &&

package/src/autonomy.ts

@@ -1,12 +1,39 @@
 import { realpathSync } from 'node:fs';
 import type { Store } from './store.js';
 import { canonical, digest, object, ServiceError, type Controller } from './protocol.js';
-export type PermissionMode = 'inspect' | 'review' | 'scoped-edit';
+export type PermissionMode =
+  | 'inspect'
+  | 'review'
+  | 'scoped-edit'
+  // Phase 2b (operator rulings 2026-10-31): the one-key modes of an interactive session.
+  | 'accept-edits'
+  | 'auto';
+const MODES: readonly PermissionMode[] = [
+  'inspect',
+  'review',
+  'scoped-edit',
+  'accept-edits',
+  'auto',
+];
+/** Modes in which the service performs no local mutation, however it was approved. */
+const READ_ONLY_MODES: readonly PermissionMode[] = ['inspect'];
+/** Shift+Tab: review → accept edits → auto → review. Full access and YOLO are never in the cycle. */
+const CYCLE: readonly PermissionMode[] = ['review', 'accept-edits', 'auto'];
+export function nextMode(mode: PermissionMode): PermissionMode {
+  const at = CYCLE.indexOf(mode);
+  return at < 0 ? 'review' : CYCLE[(at + 1) % CYCLE.length]!;
+}
+/** Sandbox levels a session can choose beyond its mode: full access (no OS sandbox; dangerous
+ * commands still ask) and YOLO (no OS sandbox and no approvals at all). */
+export type SessionAccess = 'full' | 'yolo';
 export interface PermissionPolicy {
   revision: number;
   mode: PermissionMode;
   paths: string[];
   root: string;
+  /** Present only when the person chose full access or YOLO: later commands run without the OS
+   * sandbox. Absent for sandboxed policies, so their digests (and receipts bound to them) are unchanged. */
+  access?: SessionAccess;
 }
 export function permissionPolicy(store: Store, session: string): PermissionPolicy {
   const root = store.session(session).cwd;
@@ -28,10 +55,17 @@ export function permissionPolicy(store: Store, session: string): PermissionPolic
       !Number.isSafeInteger(saved.revision) ||
       Number(saved.revision) < 1 ||
       saved.root !== root ||
-      Object.keys(saved).some((key) => !['revision', 'root', 'mode', 'paths'].includes(key))
+      Object.keys(saved).some(
+        (key) => !['revision', 'root', 'mode', 'paths', 'access'].includes(key),
+      )
     )
       throw new Error('Invalid saved policy');
-    const policy = validatePermissions({ mode: saved.mode, paths: saved.paths });
+    const policy = validatePermissions({
+      // Plan mode was removed (operator ruling 2026-10-31): a session saved in it reads as review.
+      mode: saved.mode === 'plan' ? 'review' : saved.mode,
+      paths: saved.paths,
+      ...(saved.access === undefined ? {} : { access: saved.access }),
+    });
     return { ...policy, revision: Number(saved.revision), root };
   } catch {
     throw new ServiceError(
@@ -40,15 +74,20 @@ export function permissionPolicy(store: Store, session: string): PermissionPolic
     );
   }
 }
-export function validatePermissions(value: unknown): { mode: PermissionMode; paths: string[] } {
+export function validatePermissions(value: unknown): {
+  mode: PermissionMode;
+  paths: string[];
+  access?: SessionAccess;
+} {
   const input = object(value);
   if (
-    Object.keys(input).some((k) => !['mode', 'paths'].includes(k)) ||
-    !['inspect', 'review', 'scoped-edit'].includes(String(input.mode))
+    Object.keys(input).some((k) => !['mode', 'paths', 'access'].includes(k)) ||
+    !(MODES as readonly string[]).includes(String(input.mode)) ||
+    (input.access !== undefined && input.access !== 'full' && input.access !== 'yolo')
   )
     throw new ServiceError(
       'invalid_permissions',
-      'Choose inspect, review or scoped-edit; unknown policy fields are rejected',
+      'Choose inspect, review, scoped-edit, accept-edits or auto, and access "full", "yolo" or none; unknown policy fields are rejected',
     );
   const paths = input.paths ?? [];
   if (
@@ -81,7 +120,13 @@ export function validatePermissions(value: unknown): { mode: PermissionMode; pat
       'invalid_permissions',
       'Only scoped-edit takes paths, and requires at least one',
     );
-  return { mode: input.mode as PermissionMode, paths: [...paths].sort() };
+  return {
+    mode: input.mode as PermissionMode,
+    paths: [...paths].sort(),
+    ...(input.access === 'full' || input.access === 'yolo'
+      ? { access: input.access as SessionAccess }
+      : {}),
+  };
 }
 export function configurePermissions(
   store: Store,
@@ -90,8 +135,23 @@ export function configurePermissions(
   expected: number,
   value: unknown,
   actor: Controller,
+  /** The operator's settings: may an interactive session choose full access or YOLO, and is this a
+   * desk session (YOLO is never for host-managed, board or child work)? */
+  opts: { allowFullAccess?: boolean; allowYolo?: boolean; deskSession?: boolean } = {},
 ) {
   const policy = validatePermissions(value);
+  if (policy.access === 'full' && opts.allowFullAccess === false)
+    throw new ServiceError(
+      'full_access_denied',
+      'The operator does not allow full access on this host; commands stay in the OS sandbox',
+    );
+  if (policy.access === 'yolo' && (opts.allowYolo === false || opts.deskSession !== true))
+    throw new ServiceError(
+      'yolo_denied',
+      opts.deskSession !== true
+        ? 'YOLO is only for your own desk sessions, never host-managed, board or child work'
+        : 'The operator does not allow YOLO on this host; commands keep their approvals',
+    );
   return store.request(
     'local-operator',
     request,
@@ -104,7 +164,7 @@ export function configurePermissions(
           'permissions_unavailable',
           'This policy applies only to local workspace sessions, not managed stations or child workers',
         );
-      if (policy.mode !== 'inspect' && !store.localCoding(session))
+      if (!READ_ONLY_MODES.includes(policy.mode) && !store.localCoding(session))
         throw new ServiceError(
           'local_denied',
           'Create a coding session first; policy cannot grant missing coding capability',
@@ -140,7 +200,7 @@ export function assertPermissionBinding(
   root: string,
 ): void {
   const policy = permissionPolicy(store, session);
-  if (policy.root !== root || policy.mode === 'inspect')
+  if (policy.root !== root || READ_ONLY_MODES.includes(policy.mode))
     throw new ServiceError('permission_denied', 'Current policy does not permit local mutations');
   const binding = store.db
     .prepare(
@@ -153,4 +213,45 @@ export function assertPermissionBinding(
       'Auto-approval belongs to an older policy; prepare and review a fresh operation',
     );
 }
+/** A project-relative path the session's modes may edit without review: not private or hidden. */
+function ordinaryProjectPath(path: string): boolean {
+  return (
+    path.length > 0 &&
+    !path.startsWith('/') &&
+    path
+      .split('/')
+      .every(
+        (part) =>
+          part !== '' &&
+          part !== '..' &&
+          !part.startsWith('.') &&
+          !['credentials', 'secrets', 'node_modules', 'vendor'].includes(part),
+      )
+  );
+}
+/** Whether this policy approves these edits by itself: scoped edits, accept-edits, auto and full
+ * access approve ordinary project edits; YOLO approves every edit. */
+export function autoApprovesEdits(policy: PermissionPolicy, paths: string[]): boolean {
+  if (policy.access === 'yolo') return paths.length > 0;
+  if (policy.mode === 'scoped-edit' && !policy.access) return matchesEditScope(policy, paths);
+  return (
+    (policy.mode === 'accept-edits' || policy.mode === 'auto' || policy.access === 'full') &&
+    paths.length > 0 &&
+    paths.every(ordinaryProjectPath)
+  );
+}
+/** Whether this policy approves a command by itself: auto inside the OS sandbox; full access unless
+ * the danger check calls the command dangerous; YOLO always. */
+export function autoApprovesCommands(
+  policy: PermissionPolicy,
+  sandboxed: boolean,
+  dangerous: boolean,
+  /** Pushes or opens a pull request: asks in every mode but YOLO (operator ruling 2026-10-31). */
+  publishes = false,
+): boolean {
+  if (policy.access === 'yolo') return true;
+  if (publishes) return false;
+  if (policy.access === 'full') return !dangerous;
+  return policy.mode === 'auto' && sandboxed;
+}
 export const permissionDigest = (policy: PermissionPolicy) => digest(JSON.parse(canonical(policy)));

package/src/cli-help.ts

@@ -53,12 +53,22 @@ salaam agents revoke GRANT_ID --session SESSION_ID
 Profiles are data in .salaam/agents/*.md with JSON front matter and a prompt body.
 Inspect the effective tools and digest before admission. Project definitions cannot
 grant themselves authority. Mutations accept --request-id and --takeover.`,
+  code: `salaam code [--continue | --new | --resume] [--cwd DIR] [--takeover]
+salaam here   (the same)
+salaam -c     (short for salaam code --continue)
+
+Work in this folder with one command: start the service if it is not running, then continue
+the folder's latest session (the default), start a new local coding session (--new), or pick
+any session from a list (--resume), this folder's sessions first. No session id needed.
+SALAAM_TERMINAL_STATUS=off stops the window-title and Herdr status reports.`,
   tui: `salaam tui [--session SESSION_ID] [--observe|--takeover] [--theme night|paper]
            [--cwd DIR] [--coding-root PRIVATE_DIR] [--coding-socket DOCKER_SOCKET]
 
 Bare sal opens the same Salaam terminal interface in a TTY.
-Ctrl+K actions · Ctrl+P sessions · Ctrl+N new · Ctrl+O approvals
-Ctrl+G changes · Ctrl+T commands · Ctrl+E external editor · Ctrl+C detach.
+Ctrl+K (empty composer) or F2 actions · Ctrl+P sessions · Ctrl+N new · Ctrl+O approvals
+Alt+G changes · Ctrl+T commands · Ctrl+G external editor · Ctrl+R history search
+F5 refresh · !command shell · Ctrl+C stops/clears, twice to detach.
+? on an empty composer (or F1) shows the keys for where you are.
 Work continues in the service when the terminal closes.`,
   remote: `salaam remote SSH_HOST [--remote-bin ABSOLUTE_PATH] [--state REMOTE_DIR]
               [--session SESSION_ID] [--observe|--takeover] [--theme night|paper]
@@ -88,9 +98,11 @@ Run the M9.1 boundary proof on a pre-provisioned local Linux Docker engine.
 Only disposable fixtures are mounted. The pinned image must already be present.
 No coding tools are enabled. A failed/unavailable backend exits nonzero.
 Cleanup reconciles the saved proof run without replaying commands.`,
-  acp: `salaam acp [--state DIR] [--coding]
+  acp: `salaam acp [--state DIR] [--local | --coding]
 
 Run the ACP v1 stdio client adapter against an already running Salaam service.
+--local creates your desk session in the editor's project folder, the same as
+salaam in a terminal there: modes, approvals with diffs, rules and /rewind.
 --coding creates owned coding sessions; the service must have --coding-root.
 Loading an existing session preserves its original tool authority.`,
   artifacts: `salaam artifacts put SESSION_ID --text TEXT [--request-id ID] [--takeover]
@@ -225,6 +237,8 @@ Status prints metadata only. Existing Anthropic keys remain compatible.`,
                      [--a2a-listen-config OWNER_ONLY_FILE]
                      [--agentpod-config OWNER_ONLY_FILE] [--mcp-config FILE]
                      [--tools-user USER]
+                     [--local-sandbox read-only|workspace-write|full-access]
+                     [--local-sandbox-read PATH,…|toolchain] [--unsandboxed-commands allow]
 salaam service status
 salaam service stop
 
@@ -232,6 +246,18 @@ salaam service stop
 USER through sudo -n -u USER on Linux. Without it, tools share the provider
 credential's OS user and start prints a warning.
 
+Local commands (session create --local-coding) run under the host OS sandbox:
+bubblewrap on Linux, Seatbelt on macOS. --local-sandbox (or SALAAM_LOCAL_SANDBOX)
+picks the level: workspace-write (default) writes only inside the workspace,
+read-only writes nothing, full-access runs commands unsandboxed with network. A
+sandboxed command has no network and cannot read outside the workspace and the
+system; --local-sandbox-read (or SALAAM_LOCAL_SANDBOX_READ) lists read-only paths
+it may also read, comma-separated, and "toolchain" adds this host's node prefix,
+~/.npm, ~/.nvm, ~/.cargo, ~/.rustup, ~/go and ~/.gitconfig where present. Home
+itself and credential directories (~/.ssh, ~/.aws, keychains …) are refused. On
+macOS commands get the real git from the active developer dir. A host with no
+usable sandbox refuses commands unless --unsandboxed-commands allow.
+
 Without --agentpod-config, start binds to ~/.config/salaam/agentpod-pins.json
 ($XDG_CONFIG_HOME/salaam) when that file exists.
 
@@ -242,7 +268,8 @@ An AgentPod daemon requires node-bound admissions and a fresh authority lease.
 Keep its private state outside the pinned workspace. Coding, external runtimes,
 effect connectors and managed MCP are unavailable in this profile.`,
   session: `salaam session create [--cwd DIR] [--request-id ID] [--coding | --local | --local-coding]
-  --local-coding allows reviewed edits and native commands (no OS sandbox)
+  --local-coding allows reviewed edits and native commands, each under the host OS sandbox
+                 (see salaam help service for levels and read paths)
   --local allows bounded local file inspection; optionally select --provider ID --model ID
 salaam session list
 salaam session inspect SESSION_ID
@@ -295,6 +322,7 @@ const globalOptions = `Global options:
   -h, --help     Show help without starting a service or model request.
   -V, --version  Show the installed version.`;
 export function cliHelp(group?: string): string | undefined {
+  if (group === 'here') group = 'code';
   if (group) return commands[group] ? `${commands[group]}\n\n${globalOptions}` : undefined;
   return `Salaam — persistent coding sessions
 
@@ -302,6 +330,7 @@ Usage: salaam <command> [options]
        sal <command> [options]
 
 Commands:
+  code          Work in this folder: continue its session or start one (also: here, -c)
   tui           Open the Salaam terminal interface (also bare sal)
   remote        Open the same session over SSH
   providers     List pinned Pi providers and capabilities