ticlawk 0.1.16 → 0.1.17-dev.1

package/README.md

@@ -230,6 +230,8 @@ Commands:
   profile  list or switch saved local identities
   message  send/read chat messages (agent CLI surface)
   task     claim/update/list tasks (agent CLI surface)
+  goal     report FSM transitions / signal goal changes (agent CLI surface)
+  approval canonical goal-loop approval request/resolve (agent CLI surface)
   charter  get/set conversation goal and role spec (agent CLI surface)
   group    create/list/delete groups, manage charters/members (agent CLI surface)
   dashboard   set/get conversation dashboards (agent CLI surface)

package/bin/ticlawk.mjs

@@ -57,6 +57,11 @@ import {
   runMessageCheckCommand,
   runMessageReactCommand,
   runMessageReadCommand,
+  runGoalChangedCommand,
+  runGoalReportCommand,
+  runApprovalRequestCommand,
+  runApprovalResolveCommand,
+  runApprovalListCommand,
   runMessageSearchCommand,
   runMessageSendCommand,
   runProfileShowCommand,
@@ -129,6 +134,8 @@ Commands:
   profile  list or switch saved local identities
   message  send/read chat messages (agent CLI surface)
   task     claim/update/list tasks (agent CLI surface)
+  goal     report FSM transitions / signal goal changes (agent CLI surface)
+  approval canonical goal-loop approval request/resolve (agent CLI surface)
   charter  get/set conversation goal and role spec (agent CLI surface)
   group    create/list/delete groups, manage charters/members (agent CLI surface)
   dashboard   set/get conversation dashboards (agent CLI surface)
@@ -470,6 +477,46 @@ async function main() {
     process.exit(1);
   }
 
+  if (command === 'goal') {
+    const sub = args._[1];
+    if (args.help || args.h || !sub) {
+      console.log(AGENT_COMMAND_HELP.goal);
+      return;
+    }
+    if (sub === 'report') {
+      process.exitCode = await runGoalReportCommand(args);
+      return;
+    }
+    if (sub === 'changed') {
+      process.exitCode = await runGoalChangedCommand(args);
+      return;
+    }
+    console.error(`unknown goal subcommand: ${sub}`);
+    process.exit(1);
+  }
+
+  if (command === 'approval') {
+    const sub = args._[1];
+    if (args.help || args.h || !sub) {
+      console.log(AGENT_COMMAND_HELP.approval);
+      return;
+    }
+    if (sub === 'request') {
+      process.exitCode = await runApprovalRequestCommand(args);
+      return;
+    }
+    if (sub === 'resolve') {
+      process.exitCode = await runApprovalResolveCommand(args);
+      return;
+    }
+    if (sub === 'list') {
+      process.exitCode = await runApprovalListCommand(args);
+      return;
+    }
+    console.error(`unknown approval subcommand: ${sub}`);
+    process.exit(1);
+  }
+
   if (command === 'workstream') {
     const sub = args._[1];
     if (args.help || args.h || !sub) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticlawk",
-  "version": "0.1.16",
+  "version": "0.1.17-dev.1",
   "description": "Local connector that links agent harnesses (Claude Code, Codex, OpenClaw, opencode, Pi) to the Ticlawk mobile app.",
   "type": "module",
   "main": "ticlawk.mjs",

package/src/adapters/ticlawk/api.mjs

@@ -152,13 +152,13 @@ export async function updateChannel(id, updates) {
 
 // ── Deliveries (replaces legacy message_jobs poll/ack) ──
 
-export async function claimPendingDeliveries(hostId, limit = 5, excludedAgentIds = []) {
+export async function claimPendingDeliveries(hostId, limit = 5, excludedChannels = []) {
   const { data } = await apiFetch('/api/agent/deliveries/claim-pending', {
     method: 'POST',
     body: JSON.stringify(withTiclawkVersion({
       runtime_host_id: hostId,
       limit,
-      excluded_agent_ids: excludedAgentIds,
+      excluded_channels: excludedChannels,
     })),
   });
   return data || [];
@@ -286,6 +286,71 @@ export async function updateAgentTask({ actingAgentId, taskId, status }) {
   });
 }
 
+export async function reportGoalTransition({
+  actingAgentId, conversationId, transitionId, outcome, detail, currentTaskId,
+}) {
+  return apiFetch('/api/agent/goal/report', {
+    method: 'POST',
+    body: JSON.stringify({
+      acting_as_agent_id: actingAgentId,
+      conversation_id: conversationId,
+      transition_id: transitionId,
+      outcome,
+      detail: detail ?? null,
+      current_task_id: currentTaskId ?? null,
+    }),
+  });
+}
+
+export async function noteGoalChanged({ actingAgentId, conversationId }) {
+  return apiFetch('/api/agent/goal/changed', {
+    method: 'POST',
+    body: JSON.stringify({
+      acting_as_agent_id: actingAgentId,
+      conversation_id: conversationId,
+    }),
+  });
+}
+
+export async function requestGoalApproval({
+  actingAgentId, conversationId, title, detail, ttlSeconds,
+}) {
+  return apiFetch('/api/agent/approval/request', {
+    method: 'POST',
+    body: JSON.stringify({
+      acting_as_agent_id: actingAgentId,
+      conversation_id: conversationId,
+      title,
+      detail: detail ?? null,
+      ttl_seconds: ttlSeconds ?? null,
+    }),
+  });
+}
+
+export async function listGoalApprovals({ actingAgentId, conversationId }) {
+  const params = new URLSearchParams();
+  params.set('acting_as_agent_id', actingAgentId);
+  params.set('conversation_id', conversationId);
+  const { data } = await apiFetch(`/api/agent/approval/list?${params}`);
+  return data || [];
+}
+
+export async function resolveGoalApproval({
+  actingAgentId, requestId, decision, originalText, confidence, sourceMessageId,
+}) {
+  return apiFetch('/api/agent/approval/resolve', {
+    method: 'POST',
+    body: JSON.stringify({
+      acting_as_agent_id: actingAgentId,
+      request_id: requestId,
+      decision,
+      original_text: originalText ?? null,
+      confidence: confidence ?? null,
+      source_message_id: sourceMessageId ?? null,
+    }),
+  });
+}
+
 export async function listAgentTasks({ actingAgentId, conversationId }) {
   const params = new URLSearchParams();
   params.set('acting_as_agent_id', actingAgentId);

package/src/adapters/ticlawk/index.mjs

@@ -13,6 +13,7 @@ import * as api from './api.mjs';
 import { persistApiCredential, persistRuntimeCredentials } from './credentials.mjs';
 import { TiclawkWakeClient } from './wake-client.mjs';
 import { buildInboundWakePrompt } from '../../runtimes/_shared/wake-prompt.mjs';
+import { buildGoalStepPrompt } from '../../runtimes/_shared/goal-step-prompt.mjs';
 
 const require = createRequire(import.meta.url);
 const qrcode = require('qrcode-terminal');
@@ -80,19 +81,23 @@ export function normalizeInboundMessage(msg) {
   const deliveryId = msg.delivery_id || null;
   const media = normalizeInboundMediaAssets(msg);
   const enriched = { ...msg, id: messageId };
-  const wakePrompt = buildInboundWakePrompt(enriched);
+  const isTransition = msg.reason === 'transition';
+  // A transition delivery is a goal-lane FSM step, not a chat message: it has
+  // no backing message, so build a per-step goal prompt from its payload.
+  const wakePrompt = isTransition ? buildGoalStepPrompt(enriched) : buildInboundWakePrompt(enriched);
   return {
     bindingId: recipientAgentId,
     messageId,
     deliveryId,
     conversationId: msg.conversation_id || null,
+    lane: isTransition ? 'goal' : 'chat',
     seq: msg.seq != null ? Number(msg.seq) : null,
     senderType: msg.sender_type || 'human',
     envelopeHeader: wakePrompt.header,
     envelopeTarget: wakePrompt.target,
     text: wakePrompt.text,
     rawText: wakePrompt.rawText,
-    action: msg.action || (media.length > 0 ? 'image' : 'task'),
+    action: isTransition ? 'transition' : (msg.action || (media.length > 0 ? 'image' : 'task')),
     media,
     raw: {
       ...msg,
@@ -130,6 +135,19 @@ function getAgentIdFromPayload(payload) {
   return String(payload?.recipient_agent_id || '').trim();
 }
 
+// Two lanes run concurrently per agent (see the lane-aware claim RPC):
+// the goal lane carries FSM transition deliveries (reason='transition'),
+// everything else is the user-facing chat lane. The claim unit and the
+// daemon's in-flight key are the (agent, lane) channel, so a running chat
+// turn and a running goal transition never block each other.
+function getDeliveryLaneFromPayload(payload) {
+  return payload?.reason === 'transition' ? 'goal' : 'chat';
+}
+
+function channelKeyFor(agentId, lane) {
+  return `${agentId}:${lane}`;
+}
+
 // Whitelist of meta keys runtimes actually consume. Anything else in
 // the source row's meta blob is dropped on the floor so stale fields
 // (like the post-Y2 workdir/cwd/projectDir leftovers) can't sneak
@@ -140,7 +158,11 @@ const RUNTIME_META_KEYS = [
   'runtimePath',
   'rotatePending',
   'lastRotatedAt',
-  'conversationSessions',
+  // Per-lane scoped session maps (keyed by conversation): the chat lane and
+  // the goal-FSM lane keep separate runtime sessions so a transition turn
+  // never resumes a user-chat session or vice-versa.
+  'chatSessions',
+  'goalSessions',
   // claude_code
   'claudePath',
   'claudeVersion',
@@ -642,6 +664,91 @@ export function createTiclawkAdapter(ctx) {
     }
   }
 
+  // The goal lane's canonical completion is `ticlawk goal report`, which
+  // completes the transition delivery inside report_goal_transition (before
+  // emitting the next step) so the live-transition slot frees up. By the time
+  // the turn returns the row is usually already 'completed', so this
+  // best-effort complete then 409s — that is the expected healthy path, not an
+  // error. A turn that finished without reporting leaves the row 'claimed' for
+  // stale-claimed recovery.
+  async function completeGoalDelivery(deliveryId) {
+    try {
+      await api.completeDelivery(deliveryId, hostId);
+    } catch (err) {
+      if (err?.status === 409) return;
+      throw err;
+    }
+  }
+
+  async function processGoalTransitionsForAgent(agentId, messages) {
+    for (const msg of messages) {
+      const deliveryId = msg.delivery_id;
+      const step = msg?.payload?.step || null;
+      try {
+        const messageHostId = getRuntimeHostIdFromPayload(msg);
+        if (messageHostId && messageHostId !== hostId) {
+          await api.releaseDelivery(deliveryId, hostId, 'host-mismatch');
+          continue;
+        }
+
+        const binding = await ctx.persistBinding(buildBindingFromSource(msg));
+        if (!binding?.runtime) {
+          throw new Error('claimed transition missing runtime binding');
+        }
+        if (!belongsToRuntimeHost(binding, hostId)) {
+          await api.releaseDelivery(deliveryId, hostId, 'binding-host-mismatch');
+          continue;
+        }
+
+        const completed = await ctx.bus.dispatchToAgent(binding.runtime, binding.id, normalizeInboundMessage(msg));
+        if (completed !== true) {
+          if (isTerminalRuntimeFailure(completed)) {
+            await completeGoalDelivery(deliveryId);
+            void requestDrain('transition.terminal-completed');
+            debugError('ticlawk', 'transition.terminal-failed', {
+              agentId,
+              deliveryId,
+              step,
+              runtime: binding.runtime,
+              reason: completed.reason || 'runtime terminal failure',
+            });
+            continue;
+          }
+          throw new Error('runtime did not complete transition turn');
+        }
+        await completeGoalDelivery(deliveryId);
+        void requestDrain('transition.completed');
+        debugLog('ticlawk', 'transition.completed', {
+          agentId,
+          deliveryId,
+          step,
+          runtime: binding.runtime,
+        });
+      } catch (err) {
+        if (api.isUpdateRequiredError(err)) {
+          recordUpdateRequired(err, 'transition.dispatch');
+        }
+        try {
+          await api.releaseDelivery(deliveryId, hostId, 'transition-dispatch-error');
+        } catch (releaseErr) {
+          debugError('ticlawk', 'transition.release-failed', {
+            agentId,
+            deliveryId,
+            hostId,
+            error: releaseErr?.message || 'unknown error',
+          });
+        }
+        debugError('ticlawk', 'transition.dispatch-failed', {
+          agentId,
+          deliveryId,
+          step,
+          hostId,
+          error: err?.message || 'unknown error',
+        });
+      }
+    }
+  }
+
   async function refreshBindings(reason = 'manual') {
     let channels = [];
     const startedAt = Date.now();
@@ -828,29 +935,35 @@ export function createTiclawkAdapter(ctx) {
         });
         continue;
       }
-      const bucket = grouped.get(agentId) || [];
-      bucket.push(msg);
-      grouped.set(agentId, bucket);
+      const lane = getDeliveryLaneFromPayload(msg);
+      const channelKey = channelKeyFor(agentId, lane);
+      const bucket = grouped.get(channelKey) || { agentId, lane, messages: [] };
+      bucket.messages.push(msg);
+      grouped.set(channelKey, bucket);
     }
 
     let launched = 0;
-    for (const [agentId, messages] of grouped.entries()) {
-      if (processingChannels.has(agentId)) {
+    for (const [channelKey, { agentId, lane, messages }] of grouped.entries()) {
+      if (processingChannels.has(channelKey)) {
         debugError('ticlawk', 'claim.blocked-claimed-rows', {
           reason,
+          channelKey,
           agentId,
+          lane,
           blockedRows: messages.length,
         });
         await releaseBlockedRows(agentId, messages, reason);
         continue;
       }
-      const run = processPendingMessagesForAgent(agentId, messages)
+      const run = (lane === 'goal'
+        ? processGoalTransitionsForAgent(agentId, messages)
+        : processPendingMessagesForAgent(agentId, messages))
         .catch(() => {})
         .finally(() => {
-          processingChannels.delete(agentId);
+          processingChannels.delete(channelKey);
           void requestDrain('channel.completed');
         });
-      processingChannels.set(agentId, run);
+      processingChannels.set(channelKey, run);
       launched += messages.length;
     }
 

package/src/cli/agent-commands.mjs

@@ -344,6 +344,137 @@ export async function runTaskUpdateCommand(args) {
   return exitFromStatus(res.statusCode);
 }
 
+const GOAL_OUTCOMES = [
+  'gap', 'no_gap', 'wait',
+  'task_completed', 'needs_approval', 'blocked',
+  'accepted', 'rejected',
+];
+
+export async function runGoalReportCommand(args) {
+  const env = requireAgentEnv();
+  const conversationId = getArg(args, 'conversation') || getArg(args, 'conversation-id') || env.currentConversationId;
+  const transitionId = getArg(args, 'transition') || getArg(args, 'transition-id');
+  const outcome = getArg(args, 'outcome');
+  if (!conversationId) {
+    console.error('--conversation is required');
+    return 2;
+  }
+  if (!transitionId) {
+    console.error('--transition is required');
+    return 2;
+  }
+  if (!outcome || !GOAL_OUTCOMES.includes(outcome)) {
+    console.error(`--outcome must be one of: ${GOAL_OUTCOMES.join(', ')}`);
+    return 2;
+  }
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/goal/report',
+    headers: commonHeaders(env),
+    body: {
+      conversation_id: conversationId,
+      transition_id: transitionId,
+      outcome,
+      detail: getArg(args, 'detail'),
+      current_task_id: getArg(args, 'current-task') || getArg(args, 'task-id'),
+    },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runGoalChangedCommand(args) {
+  const env = requireAgentEnv();
+  const conversationId = getArg(args, 'conversation') || getArg(args, 'conversation-id') || env.currentConversationId;
+  if (!conversationId) {
+    console.error('--conversation is required');
+    return 2;
+  }
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/goal/changed',
+    headers: commonHeaders(env),
+    body: { conversation_id: conversationId },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runApprovalRequestCommand(args) {
+  const env = requireAgentEnv();
+  const conversationId = getArg(args, 'conversation') || getArg(args, 'conversation-id') || env.currentConversationId;
+  const title = getArg(args, 'title');
+  if (!conversationId) {
+    console.error('--conversation is required');
+    return 2;
+  }
+  if (!title) {
+    console.error('--title is required');
+    return 2;
+  }
+  const ttlRaw = getArg(args, 'ttl-seconds');
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/approval/request',
+    headers: commonHeaders(env),
+    body: {
+      conversation_id: conversationId,
+      title,
+      detail: getArg(args, 'detail'),
+      ttl_seconds: ttlRaw != null ? Number(ttlRaw) : undefined,
+    },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runApprovalResolveCommand(args) {
+  const env = requireAgentEnv();
+  const requestId = getArg(args, 'request') || getArg(args, 'request-id');
+  let decision = getArg(args, 'decision');
+  if (args.grant) decision = 'granted';
+  if (args.reject) decision = 'rejected';
+  if (!requestId) {
+    console.error('--request is required');
+    return 2;
+  }
+  if (decision !== 'granted' && decision !== 'rejected') {
+    console.error('--decision must be granted or rejected (or use --grant / --reject)');
+    return 2;
+  }
+  const confidenceRaw = getArg(args, 'confidence');
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/approval/resolve',
+    headers: commonHeaders(env),
+    body: {
+      request_id: requestId,
+      decision,
+      original_text: getArg(args, 'original-text'),
+      confidence: confidenceRaw != null ? Number(confidenceRaw) : undefined,
+      source_message_id: getArg(args, 'source-message-id'),
+    },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runApprovalListCommand(args) {
+  const env = requireAgentEnv();
+  const params = new URLSearchParams();
+  const target = getArg(args, 'target');
+  const conversationId = getArg(args, 'conversation') || getArg(args, 'conversation-id') || env.currentConversationId;
+  if (target) params.set('target', target);
+  if (conversationId) params.set('conversation_id', conversationId);
+  const res = await daemonRequest({
+    method: 'GET',
+    path: `/agent/approval/list?${params}`,
+    headers: commonHeaders(env),
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
 export async function runMessageReactCommand(args) {
   const env = requireAgentEnv();
   const messageId = getArg(args, 'message-id');
@@ -1325,6 +1456,33 @@ export const AGENT_COMMAND_HELP = {
   workstream: `ticlawk workstream <create|delete|list|charter>
     Compatibility alias for group admin commands. Prefer \`ticlawk group ...\`
     for groups and \`ticlawk charter ...\` for conversation charters.
+`,
+  goal: `ticlawk goal <report|changed>
+    Goal-lane (FSM) control. Normally invoked from a goal-step turn, not by hand.
+  ticlawk goal report --transition <id> --outcome <outcome> [--conversation <id>] [--detail <text>] [--current-task <task-id>]
+    Report the outcome of the current FSM step and advance the state machine.
+    --conversation defaults to the current goal-turn conversation.
+    Outcomes by step:
+      gap_analysis: gap | no_gap | wait
+      execute:      task_completed | needs_approval | blocked
+      review:       accepted | rejected
+  ticlawk goal changed [--conversation <id>]
+    Signal that the conversation's goal changed; wakes the FSM into gap analysis.
+`,
+  approval: `ticlawk approval <request|resolve|list>
+    Canonical goal-loop approval flow. The goal lane parks on an approval and is
+    resumed by exactly one idempotent decision (button token OR chat resolver).
+  ticlawk approval request --title "<text>" [--conversation <id>] [--detail <text>] [--ttl-seconds <n>]
+    Park a pending owner approval on the goal_session (after EXECUTE reports
+    needs_approval). Returns request_id plus a one-time button action token.
+    --conversation defaults to the current goal-turn conversation.
+  ticlawk approval list [--conversation <id> | --target "<target>"]
+    List pending approval requests in the conversation. Use this from the chat
+    lane to find which request an owner's natural-language approval refers to.
+    --conversation defaults to the current conversation.
+  ticlawk approval resolve --request <id> (--grant | --reject | --decision granted|rejected) [--original-text <text>] [--confidence <0-1>] [--source-message-id <id>]
+    Resolve a pending approval from a natural-language chat decision (source=chat).
+    Idempotent: a second resolve (or a button tap) on the same request is a no-op.
 `,
   charter: `ticlawk charter <get|set> [--target "<target>" | --conversation-id <id>]
   ticlawk charter get [--target "<target>" | --conversation-id <id>]

package/src/core/agent-cli-handlers.mjs

@@ -387,6 +387,127 @@ export async function handleTaskUpdate(req, body, ctx) {
   }
 }
 
+export async function handleGoalReport(req, body, ctx) {
+  const actingAgentId = getActingAgentId(req, body);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  const conversationId = body?.conversation_id || getCurrentConversationId(req, body);
+  if (!conversationId) return { status: 400, body: { error: 'conversation_id is required' } };
+  if (!body?.transition_id) return { status: 400, body: { error: 'transition_id is required' } };
+  if (!body?.outcome) return { status: 400, body: { error: 'outcome is required' } };
+  try {
+    const data = await api.reportGoalTransition({
+      actingAgentId,
+      conversationId,
+      transitionId: body.transition_id,
+      outcome: body.outcome,
+      detail: body.detail || null,
+      currentTaskId: body.current_task_id || null,
+    });
+    debugLog('agent-cli', 'goal.report', {
+      actingAgentId,
+      conversationId,
+      outcome: body.outcome,
+      state: data?.state,
+    });
+    return { status: data?.ok ? 200 : 400, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'goal report failed' } };
+  }
+}
+
+export async function handleGoalChanged(req, body, ctx) {
+  const actingAgentId = getActingAgentId(req, body);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  const conversationId = body?.conversation_id || getCurrentConversationId(req, body);
+  if (!conversationId) return { status: 400, body: { error: 'conversation_id is required' } };
+  try {
+    const data = await api.noteGoalChanged({ actingAgentId, conversationId });
+    debugLog('agent-cli', 'goal.changed', {
+      actingAgentId,
+      conversationId,
+      goalVersion: data?.goal_version,
+    });
+    return { status: data?.ok ? 200 : 400, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'goal changed failed' } };
+  }
+}
+
+export async function handleApprovalRequest(req, body, ctx) {
+  const actingAgentId = getActingAgentId(req, body);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  const conversationId = body?.conversation_id || getCurrentConversationId(req, body);
+  if (!conversationId) return { status: 400, body: { error: 'conversation_id is required' } };
+  if (!body?.title) return { status: 400, body: { error: 'title is required' } };
+  try {
+    const data = await api.requestGoalApproval({
+      actingAgentId,
+      conversationId,
+      title: body.title,
+      detail: body.detail || null,
+      ttlSeconds: body.ttl_seconds || null,
+    });
+    debugLog('agent-cli', 'approval.request', {
+      actingAgentId,
+      conversationId,
+      requestId: data?.request_id,
+    });
+    return { status: data?.ok ? 200 : 400, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'approval request failed' } };
+  }
+}
+
+export async function handleApprovalList(req, query, ctx) {
+  const actingAgentId = getActingAgentId(req, query);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  let conversationId = query?.conversation_id || null;
+  if (!conversationId && query?.target) {
+    const resolved = await resolveTarget(actingAgentId, String(query.target));
+    if (!resolved.error) conversationId = resolved.conversationId;
+  }
+  if (!conversationId) return { status: 400, body: { error: 'conversation_id is required' } };
+  try {
+    const data = await api.listGoalApprovals({ actingAgentId, conversationId });
+    return { status: 200, body: { data } };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'approval list failed' } };
+  }
+}
+
+export async function handleApprovalResolve(req, body, ctx) {
+  const actingAgentId = getActingAgentId(req, body);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  if (!body?.request_id) return { status: 400, body: { error: 'request_id is required' } };
+  if (body?.decision !== 'granted' && body?.decision !== 'rejected') {
+    return { status: 400, body: { error: 'decision must be granted or rejected' } };
+  }
+  try {
+    const data = await api.resolveGoalApproval({
+      actingAgentId,
+      requestId: body.request_id,
+      decision: body.decision,
+      originalText: body.original_text || null,
+      confidence: body.confidence ?? null,
+      sourceMessageId: body.source_message_id || null,
+    });
+    debugLog('agent-cli', 'approval.resolve', {
+      actingAgentId,
+      requestId: body.request_id,
+      decision: body.decision,
+      resumed: data?.resumed,
+    });
+    return { status: data?.ok ? 200 : 400, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'approval resolve failed' } };
+  }
+}
+
 export async function handleTaskList(req, query, ctx) {
   const actingAgentId = getActingAgentId(req, query);
   const v = validateActingAgent(actingAgentId, ctx);

package/src/core/http.mjs

@@ -39,6 +39,11 @@ import {
   handleReminderSchedule,
   handleReminderSnooze,
   handleReminderUpdate,
+  handleGoalChanged,
+  handleGoalReport,
+  handleApprovalRequest,
+  handleApprovalResolve,
+  handleApprovalList,
   handleServerInfo,
   handleTaskClaim,
   handleTaskCreate,
@@ -144,6 +149,34 @@ export function startLocalHttpServer({ port, adapter, ctx }) {
         const r = await handleTaskList(req, parseQuery(req.url || ''), cliCtx);
         return writeJson(res, r.status, r.body);
       }
+      if (urlNoQuery === '/agent/goal/report' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleGoalReport(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/goal/changed' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleGoalChanged(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/approval/request' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleApprovalRequest(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/approval/resolve' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleApprovalResolve(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/approval/list' && method === 'GET') {
+        const r = await handleApprovalList(req, parseQuery(req.url || ''), cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
       if (urlNoQuery === '/agent/message/react' && method === 'POST') {
         const body = await readJsonBody(req);
         if (body === null) return writeJson(res, 400, { error: 'invalid json body' });

package/src/core/runtime-support.mjs

@@ -150,11 +150,22 @@ function pruneScopedRuntimeSessions(sessions) {
     .slice(0, MAX_SCOPED_RUNTIME_SESSIONS));
 }
 
+// The chat lane and the goal-FSM lane keep separate scoped session maps so a
+// transition turn never resumes a user-chat runtime session (their per-step
+// prompts and context differ). Lane is carried on the inbound; default chat.
+function laneSessionsField(lane) {
+  return lane === 'goal' ? 'goalSessions' : 'chatSessions';
+}
+
 export function resolveRuntimeSessionScope(meta = {}, inbound = {}) {
+  const lane = inbound?.lane === 'goal' ? 'goal' : 'chat';
+  const field = laneSessionsField(lane);
   const key = readScopedSessionKey(inbound);
   if (!key) {
     return {
       key: '',
+      lane,
+      field,
       sessions: {},
       sessionId: meta.sessionId || null,
       path: meta.path || null,
@@ -163,10 +174,12 @@ export function resolveRuntimeSessionScope(meta = {}, inbound = {}) {
     };
   }
 
-  const sessions = meta.rotatePending ? {} : normalizeScopedRuntimeSessions(meta.conversationSessions);
+  const sessions = meta.rotatePending ? {} : normalizeScopedRuntimeSessions(meta[field]);
   const scoped = sessions[key] || {};
   return {
     key,
+    lane,
+    field,
     sessions,
     sessionId: scoped.sessionId || null,
     path: scoped.path || null,
@@ -178,6 +191,8 @@ export function resolveRuntimeSessionScope(meta = {}, inbound = {}) {
 export function buildRuntimeSessionMetaPatch(meta = {}, scope = {}, result = {}) {
   const now = new Date().toISOString();
   const scoped = Boolean(scope.key);
+  const lane = scope.lane === 'goal' ? 'goal' : 'chat';
+  const field = scope.field || laneSessionsField(lane);
   const sessionId = result?.sessionId || scope.sessionId || (scoped ? null : meta.sessionId || null);
   const path = result?.path || scope.path || (scoped ? null : meta.path || null);
   const lastRotatedAt = scope.shouldRotate
@@ -205,11 +220,17 @@ export function buildRuntimeSessionMetaPatch(meta = {}, scope = {}, result = {})
     };
   }
 
-  return {
-    sessionId,
-    path,
-    conversationSessions: pruneScopedRuntimeSessions(sessions),
+  const patch = {
+    [field]: pruneScopedRuntimeSessions(sessions),
     rotatePending: false,
     lastRotatedAt,
   };
+  // The flat sessionId/path is the chat lane's "last used" mirror, read only
+  // by non-scoped resolution and display. The goal lane owns its own map and
+  // must not clobber that mirror.
+  if (lane === 'chat') {
+    patch.sessionId = sessionId;
+    patch.path = path;
+  }
+  return patch;
 }

package/src/runtimes/_shared/goal-step-prompt.mjs

@@ -0,0 +1,98 @@
+/**
+ * Per-step goal-lane (FSM) prompt builder.
+ *
+ * A transition delivery is an FSM event, not a chat message: it has no
+ * backing message, only a payload carrying { transition_id, kind,
+ * goal_version, step }. The goal lane runs exactly the step named in the
+ * payload, then reports the outcome with `ticlawk goal report`, which
+ * advances the state machine and (for running states) schedules the next
+ * step as a fresh transition. This is the goal-lane analogue of
+ * buildInboundWakePrompt — same {header, target, text, rawText} contract.
+ */
+
+import { buildEnvelopeTarget, buildCharterBlock } from './wake-prompt.mjs';
+
+const STEP_GUIDES = {
+  gap_analysis: {
+    title: 'GAP ANALYSIS',
+    body: `Compare the current state of the work against the goal and success criteria. Read whatever you need (charter, dashboard, task board, repo, prior messages) to judge where things actually stand.
+- If there is concrete executable work toward the goal, first make sure the next unit exists as a task (create/assign it with \`ticlawk task ...\` when a task fits), then report outcome=gap.
+- If the goal/milestone is fully met with no meaningful gap, report outcome=no_gap.
+- If closing the gap depends on a future or external state that nobody can act on right now, schedule a reminder for the resume condition, then report outcome=wait.`,
+    outcomes: ['gap', 'no_gap', 'wait'],
+  },
+  execute: {
+    title: 'EXECUTE',
+    body: `Do the next concrete unit of work toward the goal (or drive the current task to completion). Send interim updates with \`ticlawk message send --phase progress\` as you go.
+- When the unit of work is finished and ready to be checked, report outcome=task_completed.
+- If you cannot proceed without an owner approval, decision, or permission, park ONE canonical approval with \`ticlawk approval request --title "<what you need approved>" [--detail "<context>"]\`, tell the owner what you need and why with \`ticlawk message send\`, then report outcome=needs_approval. The owner's approval (button or a natural-language reply) resumes you automatically.
+- If you are blocked by something else (missing input, external failure, a needed resource), explain it to the owner, then report outcome=blocked.`,
+    outcomes: ['task_completed', 'needs_approval', 'blocked'],
+  },
+  review: {
+    title: 'REVIEW',
+    body: `Review the work that was just completed against the task and the goal.
+- If it meets the bar, mark the task done (\`ticlawk task update ... --status done\` where applicable) and report outcome=accepted.
+- If it needs rework, return it with a clean, specific redo instruction, then report outcome=rejected.`,
+    outcomes: ['accepted', 'rejected'],
+  },
+};
+
+function readPayload(msg) {
+  const payload = msg?.payload && typeof msg.payload === 'object' ? msg.payload : {};
+  return {
+    transitionId: String(payload.transition_id || '').trim(),
+    goalVersion: payload.goal_version != null ? String(payload.goal_version) : '',
+    kind: String(payload.kind || '').trim(),
+    step: String(payload.step || '').trim(),
+  };
+}
+
+function buildGoalStepHeader(msg, { step, transitionId, goalVersion, kind }) {
+  const target = buildEnvelopeTarget(msg);
+  const time = msg.created_at || new Date().toISOString();
+  return `[goal_lane target=${target} step=${step || 'unknown'} transition=${transitionId} goal_version=${goalVersion} kind=${kind} time=${time}]`;
+}
+
+export function buildGoalStepPrompt(msg) {
+  const { transitionId, goalVersion, kind, step } = readPayload(msg);
+  const target = buildEnvelopeTarget(msg);
+  const conversationId = msg.conversation_id || '';
+  const header = buildGoalStepHeader(msg, { step, transitionId, goalVersion, kind });
+  const charterBlock = buildCharterBlock(msg);
+  const guide = STEP_GUIDES[step] || null;
+
+  const reportCmd = `ticlawk goal report --conversation ${conversationId} --transition ${transitionId} --outcome <${guide ? guide.outcomes.join('|') : 'outcome'}>`;
+
+  const sections = [];
+  if (charterBlock) sections.push(charterBlock);
+
+  if (guide) {
+    sections.push([
+      `[goal_step] You are running the goal loop for this conversation. This is a backend FSM step, not a user message — do NOT treat it as something to reply to.`,
+      ``,
+      `Current step: ${guide.title}`,
+      guide.body,
+      ``,
+      `When the step is done, advance the state machine by running EXACTLY ONE report:`,
+      `  ${reportCmd}`,
+      ``,
+      `Reporting the outcome is what continues the loop: a running next state arrives as a fresh step, and the loop parks itself when there is no gap or it must wait. Send owner-facing updates with \`ticlawk message send --target ${target} --phase progress\` (use --phase final only when the loop reaches no_gap/wait/blocked-on-owner). Report exactly once; do not loop inside this single turn.`,
+      `[/goal_step]`,
+    ].join('\n'));
+  } else {
+    sections.push([
+      `[goal_step] Goal-loop FSM step with an unrecognized step "${step}". Re-evaluate the goal as a gap analysis: decide whether there is a gap, and report with:`,
+      `  ${reportCmd}`,
+      `[/goal_step]`,
+    ].join('\n'));
+  }
+
+  const text = sections.filter(Boolean).join('\n\n');
+  return {
+    header,
+    target,
+    text,
+    rawText: '',
+  };
+}

package/src/runtimes/_shared/handbook/GOAL_AUTHORITY.md

@@ -4,13 +4,29 @@ DO NOT EDIT.
 
 Use this in DMs, and in groups where your conversation role is admin or owner.
 
+The goal execution loop (gap analysis, execution, review) runs in the backend
+goal lane for this conversation — not here, and not inside your reply. You do
+NOT run that loop yourself. Your job on this (chat) side is to handle the
+incoming message and to keep the conversation's goal/charter correct so the goal
+lane has the right target. When the goal is set or changes, you wake the goal
+lane with `ticlawk goal changed`.
+
 ## Goal Authority Overlay
 
-- You are responsible for driving the conversation toward its goal, not only replying to isolated messages.
+- Handle the incoming message: reply to the user and do what it asks, then send the result. That is the end of your turn — do not start running gap analysis, creating execution tasks, or driving the goal yourself. The goal lane does that.
 - Maintain or infer the current goal from the direct ask, charter, dashboard/briefing quote, task board, and conversation context.
-- Each turn, first handle the incoming message: reply to the user and do what it asks, sending the result. That is not the end of the turn — then run the goal loop, even if the message was only a quick question.
-- If a goal exists, run the loop and drive any gap (see Goal Loop and Gap States); if none exists, decide whether this message warrants setting one (see Goal Setup When No Specific Goal Exists). The turn ends only when the loop reaches `no_gap`, `wait`, or a gap that is blocked on an owner resource/decision after you send the bundled request.
-- Until that terminal point, any chat send is `--phase progress`; send `--phase final` only after the incoming ask is handled and the goal loop has reached a stop condition.
+- If the message sets, clarifies, or changes the goal: after handling it, update the charter (when you have scope authority) and run `ticlawk goal changed --conversation <id>` to wake the goal lane into a fresh gap analysis. If the goal is unchanged, just answer — there is nothing to signal.
+- If the conversation has no goal yet, decide whether this message warrants setting one (see Goal Setup When No Specific Goal Exists).
+
+## Owner Approvals
+
+- The goal lane parks when it needs the owner to approve, decide, or grant permission, and surfaces one canonical approval request. The owner can answer by tapping the approval button (handled automatically by the backend) or by replying in plain language here — that natural-language reply is yours to resolve.
+- When an incoming message reads as the owner approving or rejecting something (e.g. "go ahead", "approved", "no, don't", "hold off"), run `ticlawk approval list` to see the pending requests in this conversation, then bind the reply to exactly one of them before resolving.
+- Bind and resolve:
+  - If the message quotes/replies to a specific approval prompt, or there is exactly one pending request, that is the target: `ticlawk approval resolve --request <id> (--grant | --reject) --original-text "<owner's words>" --source-message-id <id>`.
+  - If there are multiple pending requests and the owner's reply has no exact anchor and no unique reference, do NOT guess — ask the owner which one they mean, following `COMMUNICATION.md`.
+  - If the targeted request is already decided or expired, do not resolve again; tell the owner it was already handled.
+- Resolving is idempotent and backend-owned: a button tap and your `approval resolve` on the same request collapse to one decision, and that decision is what resumes the goal lane. You do not resume the lane yourself.
 
 ## Goal Setup When No Specific Goal Exists
 
@@ -18,23 +34,8 @@ Use this in DMs, and in groups where your conversation role is admin or owner.
 - Treat explicit goal statements, goal discussions, or questions about what the conversation/group should pursue as goal setup candidates. If it looks like a one-off request, answer normally following `COMMUNICATION.md`. Otherwise ask naturally following `COMMUNICATION.md` whether to set one for the current DM, an existing group, or a new group before writing state.
 - Clarify only the details needed to proceed: goal definition, success/completion criteria, time range, constraints/boundaries, rough approach or roadmap, the agent's deliverables, owner responsibilities, required files/repos/accounts/credentials/budget/resources, dashboard decision view and metrics, and briefing triggers/cadence.
 - Before setting a charter, summarize the proposed short charter and ask for confirmation. Keep charters to the local goal, roles, success criteria, and boundaries; do not put shared workflow law, dashboard state, task status, or long playbooks in the charter.
-- After confirmation, write the charter if you have scope authority. Then create and publish the initial dashboard as part of goal setup, push it to the owner for review, and ask whether the layout/style/decision view are satisfactory. Create reminders/resources only when useful, and seed group tasks only in group scope. Then enter the normal goal loop.
-- Treat goal setup as revisable. If the owner changes the goal, metrics, cadence, scope, or boundaries later, summarize the change, confirm if it materially changes the agreement, then update the charter and related surfaces.
-
-## Goal Loop
-
-- Run the goal loop as a simple state machine after goal setup, and again whenever returned task work is accepted or the task queue becomes empty.
-- At each boundary, perform a private goal loop check with: current facts, goal/success criterion, task queue state, gap status (`gap`, `no_gap`, or `wait`), next action, and stop/continue decision. Do not expose this check as recipient-facing content.
-- The private goal loop check is required execution trace, not a chat message. Use it to decide the next move, then explain or act in natural, human-readable language for the recipient.
-- Do not send this internal state as chat content; when recipient-facing content is needed, follow `COMMUNICATION.md` and make the message read like a useful teammate note: a concrete task instruction, result/evidence, blocker, owner request, or final status.
-- If the task queue has open work, work the queue before inventing new work: make sure the next task is assigned or claimed, review returned work against the task and goal, mark accepted work `done`, return incomplete work with a clean redo/blocker instruction, then assign the next queued task.
-- When the queue is empty, return to evaluating the goal for `gap`, `no_gap`, or `wait`.
-
-## Gap States
-
-- State `gap`: current facts show a concrete gap from the goal. Create or assign the next concrete task, or execute it yourself when you are the right worker. Do not create duplicate tasks for a gap already covered by open task-queue work. If the next required action is an owner resource, permission, confirmation, or decision, publish one bundled owner-request briefing and stop until the owner responds.
-- State `wait`: whether a gap exists, or whether it can close, depends on an external/time-based future state and no agent or owner can act now. Schedule a reminder or explicit resume condition, then stop. Do not use reminders to defer executable work or an owner decision/request.
-- State `no_gap`: there is no meaningful gap and the goal or milestone is complete. Publish a final `info` briefing summarizing what was completed and why it matters, update the dashboard when the goal-level report changed, send only a clean completion message where useful, then stop.
+- After confirmation, write the charter if you have scope authority. Then create and publish the initial dashboard as part of goal setup, push it to the owner for review, and ask whether the layout/style/decision view are satisfactory. Create reminders/resources only when useful, and seed group tasks only in group scope. Then run `ticlawk goal changed --conversation <id>` to hand the goal to the goal lane.
+- Treat goal setup as revisable. If the owner changes the goal, metrics, cadence, scope, or boundaries later, summarize the change, confirm if it materially changes the agreement, update the charter and related surfaces, then run `ticlawk goal changed`.
 
 ## State Surfaces
 

package/src/runtimes/_shared/standing-prompt.mjs

@@ -84,7 +84,7 @@ function buildCurrentConversationGuide(ctx = {}) {
 
 const FILE_DESCRIPTIONS = {
   'MEMORY.md': 'your durable memory.',
-  'GOAL_AUTHORITY.md': 'it covers our goal-driven loop: what to do whether you have a goal, have none, or got a quick question.',
+  'GOAL_AUTHORITY.md': 'goal setup and the goal-change flow (the goal loop itself runs in the backend).',
   'BASICS.md': 'workspace and work basics.',
   'COMMUNICATION.md': 'replying via the ticlawk CLI.',
   'COLLABORATION.md': 'DM/group conduct.',
@@ -96,11 +96,6 @@ const FILE_DESCRIPTIONS = {
   'TASK_WORKER.md': 'executing assigned tasks.',
 };
 
-// Files re-read at the start of every turn, not just once per session.
-// MEMORY.md for continuity; GOAL_AUTHORITY.md so the goal loop runs each turn
-// (it only appears in goal-authority scopes).
-const EVERY_TURN_FILES = new Set(['MEMORY.md', 'GOAL_AUTHORITY.md']);
-
 function describeFile(name) {
   const desc = FILE_DESCRIPTIONS[name];
   return desc ? `\`${name}\` — ${desc}` : `\`${name}\``;
@@ -108,17 +103,11 @@ function describeFile(name) {
 
 function buildReadInstructions(ctx = {}) {
   const files = buildReadFileNames(ctx);
-  const everyTurn = files.filter((name) => EVERY_TURN_FILES.has(name));
-  const once = files.filter((name) => !EVERY_TURN_FILES.has(name));
-  const everyTurnList = everyTurn.map((name, index) => `${index + 1}. ${describeFile(name)}`).join('\n');
-  const onceList = once.map((name, index) => `${index + 1}. ${describeFile(name)}`).join('\n');
+  const list = files.map((name, index) => `${index + 1}. ${describeFile(name)}`).join('\n');
   return `To reply to the user or group, use \`ticlawk message send --target <target> --phase progress|final\`. Normal assistant output is private and is not sent to the user. Details are in \`COMMUNICATION.md\`.
 
-Read these every turn before acting (they may have changed):
-${everyTurnList}
-
-Read these once if you haven't this session. Otherwise skip:
-${onceList}`;
+Read these once if you haven't this session, then only when the current work needs them:
+${list}`;
 }
 
 function buildReadFileNames(ctx = {}) {
@@ -134,12 +123,12 @@ function buildReadFileNames(ctx = {}) {
   ];
 
   if (scope === 'dm') {
-    docs.push('GOAL_TASK_CORE.md', 'GOAL_AUTHORITY.md', 'DM_SCOPE.md', 'SURFACES.md');
+    docs.push('GOAL_TASK_CORE.md', 'DM_SCOPE.md', 'SURFACES.md');
     return unique(docs);
   }
 
   if (goalAuthority) {
-    docs.push('GOAL_TASK_CORE.md', 'GOAL_AUTHORITY.md', 'GROUP_ADMIN_SCOPE.md', 'SURFACES.md');
+    docs.push('GOAL_TASK_CORE.md', 'GROUP_ADMIN_SCOPE.md', 'SURFACES.md');
     return unique(docs);
   }
 

package/src/runtimes/_shared/wake-prompt.mjs

@@ -85,9 +85,16 @@ export function buildGroupContextBlock(msg) {
 export function buildCharterBlock(msg) {
   const charter = (msg.conversation_charter || '').trim();
   if (!charter) return '';
-  const authorityLine = hasGoalAuthority(msg)
-    ? 'Use it as the current goal and role spec. If the owner appears to change the goal, read GOAL_AUTHORITY.md and follow the goal-change flow before updating state.'
-    : 'Use it as current group goal and role context. The group admin owns charter and dashboard changes unless they explicitly delegate them.';
+  const conversationId = msg.conversation_id || '';
+  // The goal lane (transition deliveries) executes against the charter; its
+  // per-step instructions come from the goal-step prompt, so here the charter
+  // is just the goal/success spec. The chat lane must NOT run the loop — it
+  // only signals goal changes to wake the goal lane.
+  const authorityLine = msg.reason === 'transition'
+    ? 'This is the goal and success spec for this conversation. Run the current step against it.'
+    : hasGoalAuthority(msg)
+      ? `This is the goal the backend goal lane is already driving. Handle the incoming message and reply; do not run a goal loop or start gap/execution work yourself. If this message sets, clarifies, or changes the goal, update the charter and then run \`ticlawk goal changed --conversation ${conversationId}\` to wake the goal lane. See GOAL_AUTHORITY.md.`
+      : 'Use it as current group goal and role context. The group admin owns charter and dashboard changes unless they explicitly delegate them.';
   return promptBlock(`
 [conversation_goal]
 Current charter for this conversation: